aha_builder_core 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ff589bfc8b84ca502361ec7db8fcd9052a02fcef786d45bdfa8f1463ab2ce92
+  data.tar.gz: 4271e05f6300fda500e3062d1ae8f2ad3ab0227cff5925919d8fd2a97c4b49c1
+SHA512:
+  metadata.gz: 3698b01b1e05371f68dd84881ac9ebda989a629def95533db97c6f48bf97803095a43ae7c6c2af6fcf6e5fe5f5700826da0a54780dccbba85860c25d92db12e8
+  data.tar.gz: 227dafe8165fc4562d26761a331bd4f128ec0ba10bdf1a2a8c859f15ee71c8ac95090f457bc772b3db9bede007f253523558294332b34fdd6acfe2fab4d96fd5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Aha! Labs Inc 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# Aha Builder Core Client
+
+Ruby client for Aha! Builder core authentication services.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "aha_builder_core", path: "engines/builder_core/client"
+```
+
+## Configuration
+
+The configuration is usually read from the environment automatically so there is no need for custom configuration in most cases.
+
+```ruby
+require "aha_builder_core"
+
+Aha::Auth.configure do |config|
+  config.server_url = "https://secure.aha.io"  # Auth server URL
+  config.client_id = "your-client-id"          # ID of the builder application
+  config.api_key = "your-api-key"              # For server-to-server auth
+  config.jwks_cache_ttl = 3600                 # JWKS cache duration (default: 1 hour)
+  config.refresh_threshold = 120               # Seconds before expiry to refresh (default: 2 min)
+  config.timeout = 30                          # HTTP timeout in seconds
+end
+```
+
+## Authentication Flow
+
+The authentication UI is provided completely by the core system. During authentication the user is redirected to the login page, and will return (via HTTP redirect) to the `/callback` URL when authentication is complete. Your application must implement a callback action at `/callback` to receive the code. Any value passed in as `state` is returned verbatim to the callback.
+
+### Generate Login URL
+
+Redirect users to the authentication and signup UI:
+
+```ruby
+url = Aha::Auth.login_url(
+  state: { return_to: "/" }.to_json,
+  redirect_uri: "#{ENV['APPLICATION_URL']}/callback"
+)
+redirect_to url
+```
+
+### Exchange Authorization Code
+
+In the `/callback` action callback, you must exchange the code for a session token and refresh token:
+
+```ruby
+result = Aha::Auth.authenticate_with_code(code: params[:code])
+# => {
+#   session_token: "...",
+#   refresh_token: "...",
+#   expires_at: Time,
+#   user: {
+#     "id" => "user-uuid",
+#     "first_name" => "Jane",
+#     "last_name" => "Doe",
+#     "email" => "jane.doe@example.com",
+#     "email_verified" => true
+#   }
+# }
+```
+
+#### User Object
+
+The `user` object returned contains the authenticated user's profile information from the Builder Core system:
+
+- `id`: The unique identifier for the user in Builder Core
+- `first_name`: User's first name
+- `last_name`: User's last name
+- `email`: User's email address
+- `email_verified`: Boolean indicating if the email has been verified
+
+#### Linking to Local User Records
+
+You can use the returned user object to create or update local user records in your application:
+
+```ruby
+# In your callback action
+result = Aha::Auth.authenticate_with_code(code: params[:code])
+
+# Find or create a local user record linked to Builder Core user
+local_user = User.find_or_initialize_by(auth_identifier: result[:user]["id"])
+
+# Update local user attributes
+local_user.update!(
+  email: result[:user]["email"],
+  first_name: result[:user]["first_name"],
+  last_name: result[:user]["last_name"],
+  email_verified: result[:user]["email_verified"]
+)
+
+# Store tokens in session or database
+session[:session_token] = result[:session_token]
+session[:refresh_token] = result[:refresh_token]
+session[:user_id] = local_user.id
+
+# Redirect to application
+redirect_to root_path
+```
+
+### Validate Session
+
+Validate a session token (with automatic refresh):
+
+```ruby
+session = Aha::Auth.validate_session(session_token, refresh_token: refresh_token)
+
+if session.valid?
+  user_id = session.user_id
+  # If tokens were refreshed, update stored tokens
+  if session.refreshed?
+    new_session_token = session.new_session_token
+    new_refresh_token = session.new_refresh_token
+  end
+else
+  # Redirect to login
+end
+```
+
+### Logout
+
+```ruby
+Aha::Auth.logout(session_token: session_token)
+```
+
+## User Management
+
+Server-to-server operations (requires `api_key`):
+
+```ruby
+# Create user
+user = Aha::Auth.users.create(
+  email: "user@example.com",
+  first_name: "Jane",
+  last_name: "Doe",
+  password: "secure_password"
+)
+
+# Find user
+user = Aha::Auth.users.find(user_id)
+
+# Update user
+user = Aha::Auth.users.update(user_id, first_name: "Janet")
+
+# Delete user
+Aha::Auth.users.delete(user_id)
+
+# List users
+result = Aha::Auth.users.list(page: 1, per_page: 50)
+result[:users]  # Array of User objects
+result[:total]  # Total count
+```
+
+## Session Management
+
+```ruby
+# List active sessions for a user
+sessions = Aha::Auth.sessions.list(user_id: user_id)
+
+# Revoke a session
+Aha::Auth.sessions.revoke(session_id)
+```
+
+## Error Handling
+
+```ruby
+begin
+  Aha::Auth.validate_session(token)
+rescue Aha::Auth::InvalidTokenError
+  # Token is malformed or has invalid signature
+rescue Aha::Auth::ExpiredTokenError
+  # Token expired and refresh failed
+rescue Aha::Auth::RateLimitError => e
+  # Rate limited, retry after e.retry_after seconds
+rescue Aha::Auth::UnauthorizedError
+  # Invalid API key
+rescue Aha::Auth::NotFoundError
+  # Resource not found
+rescue Aha::Auth::NetworkError => e
+  # Connection failed, original error in e.original_error
+rescue Aha::Auth::ApiError => e
+  # Other API error, check e.status and e.body
+end
+```

data/lib/aha/auth/client.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # HTTP client for communicating with the BuilderCore auth server
+    class Client
+      ALGORITHM = "RS256"
+
+      def initialize(configuration)
+        @configuration = configuration
+        @token_cache = TokenCache.new(ttl: configuration.jwks_cache_ttl)
+      end
+
+      # Exchange an authorization code for tokens
+      #
+      # @param code [String] The authorization code
+      # @return [Hash] Token response with :session_token, :refresh_token, :expires_at
+      def authenticate_with_code(code:)
+        response = post(
+          "/api/core/auth/authenticate", {
+            grant_type: "code",
+            code: code
+          }
+        )
+
+        parse_token_response(response)
+      end
+
+      # Refresh tokens using a refresh token
+      #
+      # @param refresh_token [String] The refresh token
+      # @return [Hash] Token response with :session_token, :refresh_token, :expires_at
+      def authenticate_with_refresh_token(refresh_token:)
+        response = post(
+          "/api/core/auth/authenticate", {
+            grant_type: "refresh_token",
+            refresh_token: refresh_token
+          }
+        )
+
+        parse_token_response(response)
+      end
+
+      # Validate a session token locally using cached JWKS
+      #
+      # @param session_token [String] The JWT session token
+      # @param refresh_token [String, nil] Optional refresh token for automatic refresh
+      # @return [Session] Session validation result
+      def validate_session(session_token, refresh_token: nil)
+        claims = decode_and_verify_token(session_token)
+        return Session.invalid unless claims
+
+        # Check if token is about to expire and we have a refresh token
+        exp = claims["exp"]
+        if exp && refresh_token && should_refresh?(exp)
+          begin
+            tokens = refresh_tokens(refresh_token: refresh_token)
+            new_claims = decode_and_verify_token(tokens[:session_token])
+
+            return Session.from_claims(
+              new_claims || claims,
+              refreshed: true,
+              new_session_token: tokens[:session_token],
+              new_refresh_token: tokens[:refresh_token]
+            )
+          rescue Error
+            puts "Token refresh failed"
+            # Refresh failed, return session with original token if still valid
+            return Session.invalid if Time.at(exp).utc < Time.now.utc
+          end
+        end
+
+        Session.from_claims(claims)
+      rescue InvalidTokenError, ExpiredTokenError
+        Session.invalid
+      end
+
+      # Logout and revoke the session
+      #
+      # @param session_token [String] The session token to revoke
+      # @return [Boolean] true if successful
+      def logout(session_token:)
+        get("/api/core/auth/logout", headers: { "Authorization" => "Bearer #{session_token}" })
+        true
+      rescue ApiError
+        false
+      end
+
+      # Fetch JWKS from the server
+      #
+      # @return [Hash] The JWKS response
+      def fetch_jwks
+        response = http_client.get("/api/core/auth/jwks/#{@configuration.client_id}")
+        handle_response(response)
+      end
+
+      private
+
+      def decode_and_verify_token(token)
+        # First decode without verification to get the header
+        header = JWT.decode(token, nil, false).last
+        kid = header["kid"]
+
+        # Get the public key for this key ID
+        public_key = @token_cache.get_key(kid) { fetch_jwks }
+
+        unless public_key
+          # Try refreshing the cache in case there's a new key
+          @token_cache.refresh! { fetch_jwks }
+          public_key = @token_cache.get_key(kid) { fetch_jwks }
+          raise InvalidTokenError, "Unknown key ID: #{kid}" unless public_key
+        end
+
+        # Verify the token
+        options = {
+          algorithm: ALGORITHM,
+          verify_expiration: true
+        }
+
+        decoded = JWT.decode(token, public_key, true, options)
+        decoded.first
+      rescue JWT::ExpiredSignature
+        raise ExpiredTokenError, "Token has expired"
+      rescue JWT::DecodeError => e
+        raise InvalidTokenError, "Invalid token: #{e.message}"
+      end
+
+      def should_refresh?(exp)
+        Time.at(exp).utc - Time.now.utc <= @configuration.refresh_threshold
+      end
+
+      def parse_token_response(response)
+        {
+          session_token: response["session_token"],
+          refresh_token: response["refresh_token"],
+          expires_at: response["expires_at"] ? Time.iso8601(response["expires_at"]) : nil,
+          user: response["user"]
+        }
+      end
+
+      def get(path, headers: {})
+        response = http_client.get(path) do |req|
+          headers.each { |k, v| req.headers[k] = v }
+        end
+        handle_response(response)
+      end
+
+      def post(path, body)
+        response = http_client.post(path) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+        handle_response(response)
+      end
+
+      def delete(path)
+        response = http_client.delete(path)
+        handle_response(response)
+      end
+
+      def http_client
+        @http_client ||= Faraday.new(url: @configuration.server_url) do |conn|
+          conn.request :retry, max: 2, interval: 0.5, backoff_factor: 2
+          conn.options.timeout = @configuration.timeout
+
+          if @configuration.api_key
+            conn.headers["Authorization"] = "Bearer #{@configuration.api_key}"
+          end
+
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def handle_response(response)
+        case response.status
+        when 200..299
+          return nil if response.body.nil? || response.body.to_s.empty?
+
+          JSON.parse(response.body)
+        when 400
+          raise BadRequestError.new(error_message(response), status: response.status, body: response.body)
+        when 401
+          raise UnauthorizedError.new(error_message(response), status: response.status, body: response.body)
+        when 403
+          raise ForbiddenError.new(error_message(response), status: response.status, body: response.body)
+        when 404
+          raise NotFoundError.new(error_message(response), status: response.status, body: response.body)
+        when 429
+          retry_after = response.headers["Retry-After"]&.to_i
+          raise RateLimitError.new("Rate limit exceeded", retry_after: retry_after)
+        else
+          raise ApiError.new(error_message(response), status: response.status, body: response.body)
+        end
+      rescue Faraday::Error => e
+        raise NetworkError.new("Network error: #{e.message}", original_error: e)
+      end
+
+      def error_message(response)
+        parsed = JSON.parse(response.body)
+        parsed["error"] || parsed["message"] || "Request failed"
+      rescue JSON::ParserError
+        "Request failed with status #{response.status}"
+      end
+    end
+  end
+end

data/lib/aha/auth/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    class Configuration
+      # The base URL of the BuilderCore auth server
+      attr_accessor :server_url
+
+      # API key for server-to-server authentication
+      attr_accessor :api_key
+
+      # Client/application identifier
+      attr_accessor :client_id
+
+      # How long to cache JWKS keys (default: 1 hour)
+      attr_accessor :jwks_cache_ttl
+
+      # Number of seconds before token expiry to trigger refresh (default: 120)
+      attr_accessor :refresh_threshold
+
+      # HTTP timeout in seconds (default: 30)
+      attr_accessor :timeout
+
+      def initialize
+        @server_url = ENV.fetch("AHA_CORE_SERVER_URL", nil) || "https://secure.aha.io/api/core"
+        @api_key = ENV.fetch("AHA_CORE_API_KEY", nil)
+        @client_id = ENV.fetch("APPLICATION_ID", nil)
+        @jwks_cache_ttl = 3600 # 1 hour
+        @refresh_threshold = 120 # 2 minutes
+        @timeout = 30
+      end
+
+      def validate!
+        raise ConfigurationError, "server_url is required" if server_url.nil? || server_url.to_s.empty?
+        raise ConfigurationError, "client_id is required" if client_id.nil? || client_id.to_s.empty?
+      end
+    end
+  end
+end

data/lib/aha/auth/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # Base error class for all Aha::Auth errors
+    class Error < StandardError; end
+
+    # Raised when configuration is invalid or incomplete
+    class ConfigurationError < Error; end
+
+    # Raised when a token is malformed or has an invalid signature
+    class InvalidTokenError < Error; end
+
+    # Raised when a token has expired and refresh failed or no refresh token provided
+    class ExpiredTokenError < Error; end
+
+    # Raised when a session has been revoked server-side
+    class RevokedSessionError < Error; end
+
+    # Raised when the auth server cannot be reached
+    class NetworkError < Error
+      attr_reader :original_error
+
+      def initialize(message, original_error: nil)
+        super(message)
+        @original_error = original_error
+      end
+    end
+
+    # Raised when rate limit is exceeded
+    class RateLimitError < Error
+      attr_reader :retry_after
+
+      def initialize(message, retry_after: nil)
+        super(message)
+        @retry_after = retry_after
+      end
+    end
+
+    # Raised for API errors from the server
+    class ApiError < Error
+      attr_reader :status, :body
+
+      def initialize(message, status: nil, body: nil)
+        super(message)
+        @status = status
+        @body = body
+      end
+    end
+
+    # Raised when a requested resource is not found
+    class NotFoundError < ApiError; end
+
+    # Raised when the request is unauthorized (invalid API key)
+    class UnauthorizedError < ApiError; end
+
+    # Raised when the request is forbidden
+    class ForbiddenError < ApiError; end
+
+    # Raised when the request is invalid
+    class BadRequestError < ApiError; end
+  end
+end

data/lib/aha/auth/session.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # Represents a validated session with user and session information
+    class Session
+      attr_reader :user_id, :session_id, :expires_at, :new_session_token, :new_refresh_token
+
+      def initialize(valid:, user_id: nil, session_id: nil, expires_at: nil, refreshed: false, new_session_token: nil, new_refresh_token: nil)
+        @valid = valid
+        @user_id = user_id
+        @session_id = session_id
+        @expires_at = expires_at
+        @refreshed = refreshed
+        @new_session_token = new_session_token
+        @new_refresh_token = new_refresh_token
+      end
+
+      def valid?
+        @valid
+      end
+
+      def refreshed?
+        @refreshed
+      end
+
+      # Create an invalid session result
+      def self.invalid
+        new(valid: false)
+      end
+
+      # Create a valid session from decoded JWT claims
+      def self.from_claims(claims, refreshed: false, new_session_token: nil, new_refresh_token: nil)
+        new(
+          valid: true,
+          user_id: claims["sub"],
+          session_id: claims["sid"],
+          expires_at: claims["exp"] ? Time.at(claims["exp"]).utc : nil,
+          refreshed: refreshed,
+          new_session_token: new_session_token,
+          new_refresh_token: new_refresh_token
+        )
+      end
+    end
+  end
+end

data/lib/aha/auth/sessions_resource.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # API resource for session management operations
+    class SessionsResource
+      # Represents a session from the auth server
+      class SessionInfo
+        attr_reader :id, :ip_address, :user_agent, :created_at, :expires_at
+
+        def initialize(attributes = {})
+          @id = attributes["id"] || attributes[:id]
+          @ip_address = attributes["ip_address"] || attributes[:ip_address]
+          @user_agent = attributes["user_agent"] || attributes[:user_agent]
+          @created_at = parse_time(attributes["created_at"] || attributes[:created_at])
+          @expires_at = parse_time(attributes["expires_at"] || attributes[:expires_at])
+        end
+
+        private
+
+        def parse_time(value)
+          return nil if value.nil?
+          return value if value.is_a?(Time)
+
+          Time.iso8601(value)
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      def initialize(client)
+        @client = client
+      end
+
+      # List active sessions for a user
+      #
+      # @param user_id [String, Integer] The user ID
+      # @return [Array<SessionInfo>] List of active sessions
+      def list(user_id:)
+        response = get("/api/core/auth/sessions", user_id: user_id)
+        response["sessions"].map { |s| SessionInfo.new(s) }
+      end
+
+      # Revoke a session
+      #
+      # @param session_id [String, Integer] The session ID to revoke
+      # @return [Boolean] true if revoked
+      def revoke(session_id)
+        delete_request("/api/core/auth/sessions/#{session_id}")
+        true
+      end
+
+      private
+
+      def get(path, params = {})
+        query = params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+        @client.send(:get, "#{path}#{query}")
+      end
+
+      def delete_request(path)
+        @client.send(:delete, path)
+      end
+    end
+  end
+end

data/lib/aha/auth/token_cache.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Aha
+  module Auth
+    # Caches JWKS public keys for JWT verification
+    class TokenCache
+      def initialize(ttl:)
+        @ttl = ttl
+        @keys = {}
+        @fetched_at = nil
+        @mutex = Mutex.new
+      end
+
+      # Get a public key by key ID, fetching from server if not cached
+      #
+      # @param kid [String] The key ID
+      # @param fetcher [Proc] A proc that fetches the JWKS from the server
+      # @return [OpenSSL::PKey::RSA, nil] The public key or nil if not found
+      def get_key(kid, &fetcher)
+        @mutex.synchronize do
+          refresh_if_needed(&fetcher)
+          @keys[kid]
+        end
+      end
+
+      # Force a refresh of the JWKS cache
+      #
+      # @param fetcher [Proc] A proc that fetches the JWKS from the server
+      def refresh!(&fetcher)
+        @mutex.synchronize do
+          fetch_keys(&fetcher)
+        end
+      end
+
+      # Check if the cache is stale
+      def stale?
+        @fetched_at.nil? || (Time.now.utc - @fetched_at) > @ttl
+      end
+
+      # Clear the cache
+      def clear!
+        @mutex.synchronize do
+          @keys = {}
+          @fetched_at = nil
+        end
+      end
+
+      private
+
+      def refresh_if_needed(&fetcher)
+        fetch_keys(&fetcher) if stale?
+      end
+
+      def fetch_keys
+        jwks = yield
+        return unless jwks && jwks["keys"]
+
+        @keys = {}
+        jwks["keys"].each do |key_data|
+          next unless key_data["kty"] == "RSA"
+
+          kid = key_data["kid"]
+          @keys[kid] = build_rsa_key(key_data)
+        end
+        @fetched_at = Time.now.utc
+      end
+
+      def build_rsa_key(key_data)
+        n = OpenSSL::BN.new(base64url_decode(key_data["n"]), 2)
+        e = OpenSSL::BN.new(base64url_decode(key_data["e"]), 2)
+
+        # Build RSA public key from modulus (n) and exponent (e)
+        # Use ASN.1 sequence for OpenSSL 3.0+ compatibility
+        rsa_public_key = OpenSSL::ASN1::Sequence.new(
+          [
+            OpenSSL::ASN1::Integer(n),
+            OpenSSL::ASN1::Integer(e)
+          ]
+        )
+        algorithm_id = OpenSSL::ASN1::Sequence.new(
+          [
+            OpenSSL::ASN1::ObjectId("rsaEncryption"),
+            OpenSSL::ASN1::Null.new(nil)
+          ]
+        )
+        asn1 = OpenSSL::ASN1::Sequence.new(
+          [
+            algorithm_id,
+            OpenSSL::ASN1::BitString(rsa_public_key.to_der)
+          ]
+        )
+        OpenSSL::PKey::RSA.new(asn1.to_der)
+      end
+
+      def base64url_decode(str)
+        # Add padding if needed
+        str = str.to_s
+        str += "=" * (4 - (str.length % 4)) if str.length % 4 != 0
+        Base64.urlsafe_decode64(str)
+      end
+    end
+  end
+end

data/lib/aha/auth/user.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # Represents a user from the auth server
+    class User
+      attr_reader :id, :email, :first_name, :last_name, :email_verified, :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"] || attributes[:id]
+        @email = attributes["email"] || attributes[:email]
+        @first_name = attributes["first_name"] || attributes[:first_name]
+        @last_name = attributes["last_name"] || attributes[:last_name]
+        @email_verified = attributes["email_verified"] || attributes[:email_verified]
+        @created_at = parse_time(attributes["created_at"] || attributes[:created_at])
+        @updated_at = parse_time(attributes["updated_at"] || attributes[:updated_at])
+      end
+
+      def full_name
+        [first_name, last_name].compact.join(" ")
+      end
+
+      private
+
+      def parse_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/aha/auth/users_resource.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    # API resource for user management operations
+    class UsersResource
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a new user
+      #
+      # @param email [String] User's email address
+      # @param first_name [String] User's first name
+      # @param last_name [String] User's last name
+      # @param password [String] User's password
+      # @return [User] The created user
+      def create(email:, first_name:, last_name:, password:)
+        response = post(
+          "/api/core/auth/users", {
+            email: email,
+            first_name: first_name,
+            last_name: last_name,
+            password: password
+          }
+        )
+
+        User.new(response)
+      end
+
+      # Find a user by ID
+      #
+      # @param id [String, Integer] The user ID
+      # @return [User] The user
+      def find(id)
+        response = get("/api/core/auth/users/#{id}")
+        User.new(response)
+      end
+
+      # Update a user
+      #
+      # @param id [String, Integer] The user ID
+      # @param attributes [Hash] Attributes to update (:email, :first_name, :last_name, :password)
+      # @return [User] The updated user
+      def update(id, **attributes)
+        response = put("/api/core/auth/users/#{id}", attributes)
+        User.new(response)
+      end
+
+      # Delete a user
+      #
+      # @param id [String, Integer] The user ID
+      # @return [Boolean] true if deleted
+      def delete(id)
+        delete_request("/api/core/auth/users/#{id}")
+        true
+      end
+
+      # List users with pagination
+      #
+      # @param page [Integer] Page number (default: 1)
+      # @param per_page [Integer] Users per page (default: 50)
+      # @return [Hash] Response with :users, :total, :page
+      def list(page: 1, per_page: 50)
+        response = get("/api/core/auth/users", page: page, per_page: per_page)
+
+        {
+          users: response["users"].map { |u| User.new(u) },
+          total: response["total"],
+          page: response["page"]
+        }
+      end
+
+      private
+
+      def get(path, params = {})
+        query = params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+        @client.send(:get, "#{path}#{query}")
+      end
+
+      def post(path, body)
+        @client.send(:post, path, body)
+      end
+
+      def put(path, body)
+        response = @client.send(:http_client).put(path) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+        @client.send(:handle_response, response)
+      end
+
+      def delete_request(path)
+        @client.send(:delete, path)
+      end
+    end
+  end
+end

data/lib/aha/auth/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Aha
+  module Auth
+    VERSION = "1.0.0"
+  end
+end

data/lib/aha/auth.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "jwt"
+require "concurrent"
+
+require_relative "auth/version"
+require_relative "auth/errors"
+require_relative "auth/configuration"
+require_relative "auth/token_cache"
+require_relative "auth/session"
+require_relative "auth/user"
+require_relative "auth/client"
+require_relative "auth/users_resource"
+require_relative "auth/sessions_resource"
+
+module Aha
+  module Auth
+    CONFIGURATION = Concurrent::Atom.new(Configuration.new)
+    CLIENT = Concurrent::Atom.new(nil)
+    USERS_RESOURCE = Concurrent::Atom.new(nil)
+    SESSIONS_RESOURCE = Concurrent::Atom.new(nil)
+
+    class << self
+      def configuration
+        CONFIGURATION.value
+      end
+
+      def configure
+        yield(CONFIGURATION.value)
+      end
+
+      def reset_configuration!
+        CONFIGURATION.reset(Configuration.new)
+        CLIENT.reset(nil)
+        USERS_RESOURCE.reset(nil)
+        SESSIONS_RESOURCE.reset(nil)
+      end
+
+      # Generate login URL for redirecting users to the auth server
+      #
+      # @param state [String] Optional state parameter to pass through the auth flow
+      # @param redirect_uri [String] Optional redirect URI after authentication
+      # @return [String] The login URL
+      def login_url(state: nil, redirect_uri: nil)
+        params = { client_id: configuration.client_id }
+        params[:state] = state if state
+        params[:redirect_uri] = redirect_uri if redirect_uri
+
+        query = URI.encode_www_form(params)
+        "#{configuration.server_url}/auth/start?#{query}"
+      end
+
+      # Exchange an authorization code for tokens
+      #
+      # @param code [String] The authorization code from the callback
+      # @return [Hash] Token response with :session_token, :refresh_token, :expires_at, :user
+      def authenticate_with_code(code:)
+        client.authenticate_with_code(code: code)
+      end
+
+      # Refresh tokens using a refresh token
+      #
+      # @param refresh_token [String] The refresh token
+      # @return [Hash] Token response with :session_token, :refresh_token, :expires_at
+      def refresh_tokens(refresh_token:)
+        client.authenticate_with_refresh_token(refresh_token: refresh_token)
+      end
+
+      # Validate a session token
+      #
+      # @param session_token [String] The JWT session token
+      # @param refresh_token [String, nil] Optional refresh token for automatic refresh
+      # @return [Session] Session validation result
+      def validate_session(session_token, refresh_token: nil)
+        client.validate_session(session_token, refresh_token: refresh_token)
+      end
+
+      # Logout and revoke the session
+      #
+      # @param session_token [String] The session token to revoke
+      # @return [Boolean] true if successful
+      def logout(session_token:)
+        client.logout(session_token: session_token)
+      end
+
+      # Access the users API resource
+      #
+      # @return [UsersResource]
+      def users
+        USERS_RESOURCE.compare_and_set(nil, UsersResource.new(client))
+        USERS_RESOURCE.value
+      end
+
+      # Access the sessions API resource
+      #
+      # @return [SessionsResource]
+      def sessions
+        SESSIONS_RESOURCE.compare_and_set(nil, SessionsResource.new(client))
+        SESSIONS_RESOURCE.value
+      end
+
+      private
+
+      def client
+        CLIENT.compare_and_set(nil, Client.new(configuration))
+        CLIENT.value
+      end
+    end
+  end
+end

data/lib/aha_builder_core.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "aha/auth"

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: aha_builder_core
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Aha! Labs Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby gem providing convenient access to the authentication API for
+  session validation, user management, and authentication flows.
+email:
+- support@aha.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/aha/auth.rb
+- lib/aha/auth/client.rb
+- lib/aha/auth/configuration.rb
+- lib/aha/auth/errors.rb
+- lib/aha/auth/session.rb
+- lib/aha/auth/sessions_resource.rb
+- lib/aha/auth/token_cache.rb
+- lib/aha/auth/user.rb
+- lib/aha/auth/users_resource.rb
+- lib/aha/auth/version.rb
+- lib/aha_builder_core.rb
+homepage: https://www.aha.io
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Ruby client for Aha! Builder core services
+test_files: []