aha_builder_core 1.0.1 → 1.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cec0f75d63cf8393eb2c6130cefa3ff8f06c041536a2fc8062ca229c13647697
-  data.tar.gz: a8759f979fe6256c4627fe0bca73c4fe2dca1e0ca1f6874b03b145bfa46241f0
+  metadata.gz: 67c88ef564275000006548bd40149fb9d8c9c6a28d7b9faf430a8dd6b338147c
+  data.tar.gz: 10401cac65cfa9f711640911038c12491acaf73b160f340851becdce92edfbb2
 SHA512:
-  metadata.gz: f4e44c3f8cf0c1eb89f179ad97562e913f86e4621eba409b7868ff1cf26f24aff42810951430ea0e88a1e22c61aac7991baf9c37fc38472c1f2d6b34ef384220
-  data.tar.gz: 39a1ea75024a765fa7f74ed6b223d0de67d3aa5fb336dad99d644f42516cd8a3514e81535f7ebf0a4c4fe07395c3239bbea2b3f2f8c39522929879d0729c7f75
+  metadata.gz: f8c526217a495e3e9ec239c4d169eb0848f9bcc6f876ba92f02f114a420f0220313e7960ef1a56b1271c0d270f2906480a5524510e988ecda939eca8491e3f10
+  data.tar.gz: 1eb5ccd35517e18df03ea87a2c93b4eadea3152d79023f440ee19c9930f600543085c6c6ab2e45fccbfb3ee0df1a1bd14b0223ca11315e8826e2d655f5df5880

data/README.md

@@ -1,6 +1,6 @@
 # Aha Builder Core Client
 
-Ruby client for Aha! Builder core authentication services.
+Ruby client for Aha! Builder core authentication services which provides login and signup using email/password, social logins (Google, Github, Microsoft), SAML SSO and password reset.
 
 ## Installation
 
@@ -12,25 +12,14 @@ 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
-```
+No configuration is necessary and no environment variables are necessary.
 
 ## 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.
 
+Protection against CSRF atacks is handled internally by the Aha::Auth library and there is no need to use a nonce in the state parameter.
+
 ### Generate Login URL
 
 Redirect users to the authentication and signup UI:
@@ -38,11 +27,12 @@ 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
 ```
 
+Redirecting to the login_url must be done with a full page load. It will not work using XHR.
+
 ### Exchange Authorization Code
 
 In the `/callback` action callback, you must exchange the code for a session token and refresh token:
@@ -54,11 +44,11 @@ result = Aha::Auth.authenticate_with_code(code: params[:code])
 #   refresh_token: "...",
 #   expires_at: Time,
 #   user: {
-#     "id" => "user-uuid",
-#     "first_name" => "Jane",
-#     "last_name" => "Doe",
-#     "email" => "jane.doe@example.com",
-#     "email_verified" => true
+#     id: "user-uuid",
+#     first_name: "Jane",
+#     last_name: "Doe",
+#     email: "jane.doe@example.com",
+#     email_verified: true
 #   }
 # }
 ```
@@ -68,8 +58,8 @@ result = Aha::Auth.authenticate_with_code(code: params[:code])
 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
+- `first_name`: User's first name. first_name is optional and may not be present.
+- `last_name`: User's last name. last_name is optional and may not be present.
 - `email`: User's email address
 - `email_verified`: Boolean indicating if the email has been verified
 
@@ -86,10 +76,10 @@ 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"]
+  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

data/lib/aha/auth/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/hash/indifferent_access"
+
 module Aha
   module Auth
     # HTTP client for communicating with the BuilderCore auth server
@@ -47,14 +49,16 @@ module Aha
       # @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
+        begin
+          claims = decode_and_verify_token(session_token)
+          return Session.from_claims(claims) if claims
+        rescue ExpiredTokenError 
+          # Token has expired, attempt refresh
+        end
 
-        # Check if token is about to expire and we have a refresh token
-        exp = claims["exp"]
-        if exp && refresh_token && should_refresh?(exp)
+        if refresh_token
           begin
-            tokens = refresh_tokens(refresh_token: refresh_token)
+            tokens = authenticate_with_refresh_token(refresh_token: refresh_token)
             new_claims = decode_and_verify_token(tokens[:session_token])
 
             return Session.from_claims(
@@ -64,13 +68,11 @@ module Aha
               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
+            return Session.invalid
           end
         end
 
-        Session.from_claims(claims)
+        Session.invalid
       rescue InvalidTokenError, ExpiredTokenError
         Session.invalid
       end
@@ -80,7 +82,7 @@ module Aha
       # @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}" })
+        get("/api/core/auth_ui/logout", headers: { "Authorization" => "Bearer #{session_token}" })
         true
       rescue ApiError
         false
@@ -90,8 +92,7 @@ module Aha
       #
       # @return [Hash] The JWKS response
       def fetch_jwks
-        response = http_client.get("/api/core/auth/jwks/#{@configuration.client_id}")
-        handle_response(response)
+        get("/api/core/auth/jwks/#{@configuration.client_id}")
       end
 
       private
@@ -125,17 +126,13 @@ module Aha
         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"]
-        }
+        }.with_indifferent_access
       end
 
       def get(path, headers: {})

data/lib/aha/auth/configuration.rb

@@ -22,7 +22,7 @@ module Aha
       attr_accessor :timeout
 
       def initialize
-        @server_url = ENV.fetch("AHA_CORE_SERVER_URL", nil) || "https://secure.aha.io/api/core"
+        @server_url = ENV.fetch("AHA_CORE_SERVER_URL", "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

data/lib/aha/auth/sessions_resource.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module Aha
   module Auth
     # API resource for session management operations

data/lib/aha/auth/user.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module Aha
   module Auth
     # Represents a user from the auth server

data/lib/aha/auth/version.rb

@@ -2,6 +2,6 @@
 
 module Aha
   module Auth
-    VERSION = "1.0.1"
+    VERSION = "1.0.4"
   end
 end

data/lib/aha/auth.rb

@@ -4,6 +4,8 @@ require "faraday"
 require "faraday/retry"
 require "jwt"
 require "concurrent"
+require "active_support"
+require "active_support/core_ext"
 
 require_relative "auth/version"
 require_relative "auth/errors"
@@ -40,24 +42,59 @@ module Aha
 
       # Generate login URL for redirecting users to the auth server
       #
+      # @param session [Hash] Session hash to store the nonce for CSRF verification
       # @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
+      def login_url(session:, state: nil)
+        # Generate a nonce for CSRF protection
+        nonce = SecureRandom.hex(10)
+
+        # Store nonce in the client's session if provided
+        session[:auth_nonce] = nonce if session
+
+        # Encode the state with nonce
+        state_data = {
+          tunneled_state: state,
+          nonce: nonce,
+        }
+
+        encoded_state = Base64.urlsafe_encode64(state_data.to_json, padding: false)
+
+        params = {
+          client_id: configuration.client_id,
+          state: encoded_state
+        }
 
         query = URI.encode_www_form(params)
-        "#{configuration.server_url}/auth/start?#{query}"
+        "#{configuration.server_url}/auth_ui/start?#{query}"
       end
 
       # Exchange an authorization code for tokens
       #
-      # @param code [String] The authorization code from the callback
+      # @param code [String] The authorization code from the callback (may include nonce)
+      # @param session [Hash] Session hash containing the nonce for CSRF verification
       # @return [Hash] Token response with :session_token, :refresh_token, :expires_at, :user
-      def authenticate_with_code(code:)
-        client.authenticate_with_code(code: code)
+      def authenticate_with_code(code:, session:)
+        # Split the code and nonce if present
+        actual_code, nonce = code.split(".", 2)
+
+        # Verify CSRF protection if nonce is present
+        if nonce
+          session_nonce = session[:auth_nonce]
+
+          # Verify nonce matches
+          if session_nonce.blank? || session_nonce != nonce
+            raise "CSRF verification failed: nonce mismatch"
+          end
+
+          # Clear the nonce from session after verification
+          session.delete(:auth_nonce)
+        else
+          # If we fon't have a none, we can't verify CSRF.
+          raise "CSRF verification failed: unable to verify nonce"
+        end
+
+        client.authenticate_with_code(code: actual_code)
       end
 
       # Refresh tokens using a refresh token

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: aha_builder_core
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.4
 platform: ruby
 authors:
 - Aha! Labs Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-21 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -111,12 +125,6 @@ files:
 - lib/aha/auth/users_resource.rb
 - lib/aha/auth/version.rb
 - lib/aha_builder_core.rb
-- lib/generators/aha_builder_core/authentication/USAGE
-- lib/generators/aha_builder_core/authentication/authentication_generator.rb
-- lib/generators/aha_builder_core/authentication/templates/authentication.rb.erb
-- lib/generators/aha_builder_core/authentication/templates/current.rb.erb
-- lib/generators/aha_builder_core/authentication/templates/sessions_controller.rb.erb
-- lib/generators/aha_builder_core/authentication/templates/user.rb.erb
 homepage: https://www.aha.io
 licenses:
 - MIT

data/lib/generators/aha_builder_core/authentication/USAGE

@@ -1,21 +0,0 @@
-Description:
-    Generates authentication setup for Aha! Builder Core client
-
-    This generator creates:
-    - SessionsController with new and callback actions for authentication flow
-    - User model for storing authenticated user information
-    - Current model for thread-isolated current user access
-    - Authentication concern to be included in ApplicationController
-
-Example:
-    bin/rails generate aha_builder_core:authentication
-
-    This will create:
-        app/controllers/sessions_controller.rb
-        app/controllers/concerns/authentication.rb
-        app/models/user.rb
-        app/models/current.rb
-
-    And add routes:
-        get "login", to: "sessions#new", as: :new_session
-        get "callback", to: "sessions#callback", as: :session_callback

data/lib/generators/aha_builder_core/authentication/authentication_generator.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-require "rails/generators"
-
-module AhaBuilderCore
-  module Generators
-    class AuthenticationGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
-      def create_sessions_controller
-        template "sessions_controller.rb.erb", "app/controllers/sessions_controller.rb"
-      end
-
-      def create_user_model
-        template "user.rb.erb", "app/models/user.rb"
-      end
-
-      def create_current_model
-        template "current.rb.erb", "app/models/current.rb"
-      end
-
-      def create_authentication_concern
-        template "authentication.rb.erb", "app/controllers/concerns/authentication.rb"
-      end
-
-      def add_routes
-        route <<~RUBY
-          get "login", to: "sessions#new", as: :new_session
-          get "callback", to: "sessions#callback", as: :session_callback
-        RUBY
-      end
-
-      def display_instructions
-        say "\nAuthentication setup complete!", :green
-        say "\nNext steps:"
-        say "1. Configure your environment variables:"
-        say "   - APPLICATION_URL: Your application's base URL"
-        say "   - AHA_AUTH_SERVER_URL: The authentication server URL"
-        say "   - AHA_AUTH_CLIENT_ID: Your client ID"
-        say "   - AHA_AUTH_API_KEY: Your API key (if using server-to-server operations)"
-        say "\n2. Run migrations to create the users table:"
-        say "   rails generate migration CreateUsers auth_identifier:string:index email:string first_name:string last_name:string email_verified:boolean"
-        say "   rails db:migrate"
-        say "\n3. Include authentication in ApplicationController:"
-        say "   include Authentication"
-        say "\n4. Protect routes with:"
-        say "   before_action :authenticate"
-      end
-
-      private
-
-      def application_name
-        Rails.application.class.module_parent.name
-      end
-    end
-  end
-end

data/lib/generators/aha_builder_core/authentication/templates/authentication.rb.erb

@@ -1,48 +0,0 @@
-module Authentication
-  extend ActiveSupport::Concern
-
-  included do
-    before_action :authenticate
-    helper_method :current_user, :logged_in?
-  end
-
-  private
-
-  def authenticate
-    if session[:session_token].present?
-      session_result = Aha::Auth.validate_session(
-        session[:session_token],
-        refresh_token: session[:refresh_token]
-      )
-
-      if session_result.valid?
-        # If tokens were refreshed, update stored tokens
-        if session_result.refreshed?
-          session[:session_token] = session_result.new_session_token
-          session[:refresh_token] = session_result.new_refresh_token
-        end
-
-        # Set current user
-        @current_user = User.find_by(id: session[:user_id])
-        Current.user = @current_user
-      else
-        reset_session
-        redirect_to new_session_path, alert: "Your session has expired. Please log in again."
-      end
-    else
-      redirect_to new_session_path
-    end
-  rescue Aha::Auth::ApiError => e
-    Rails.logger.error "Session validation failed: #{e.message}"
-    reset_session
-    redirect_to new_session_path, alert: "Authentication error. Please log in again."
-  end
-
-  def current_user
-    @current_user ||= Current.user
-  end
-
-  def logged_in?
-    current_user.present?
-  end
-end

data/lib/generators/aha_builder_core/authentication/templates/current.rb.erb

@@ -1,4 +0,0 @@
-# Provides a thread-isolated attributes singleton for current user
-class Current < ActiveSupport::CurrentAttributes
-  attribute :user
-end

data/lib/generators/aha_builder_core/authentication/templates/sessions_controller.rb.erb

@@ -1,44 +0,0 @@
-class SessionsController < ApplicationController
-  skip_before_action :authenticate, only: [:new, :callback]
-
-  def new
-    # Start authentication by redirecting to the auth URL
-    redirect_to Aha::Auth.login_url(
-      state: { return_to: params[:return_to] || root_path }.to_json,
-      redirect_uri: "#{ENV['APPLICATION_URL']}/callback"
-    ), allow_other_host: true
-  end
-
-  def callback
-    # Handle the callback from the authentication server
-    if params[:code].present?
-      result = Aha::Auth.authenticate_with_code(code: params[:code])
-
-      # Find or create a local user record linked to Builder Core user
-      user = User.find_or_initialize_by(auth_identifier: result[:user]["id"])
-
-      # Update local user attributes
-      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
-      session[:session_token] = result[:session_token]
-      session[:refresh_token] = result[:refresh_token]
-      session[:user_id] = user.id
-
-      # Parse state to get return_to path
-      state = JSON.parse(params[:state]) rescue {}
-      redirect_to state["return_to"] || root_path
-    else
-      # Authentication failed or was cancelled
-      redirect_to new_session_path, alert: "Authentication failed. Please try again."
-    end
-  rescue Aha::Auth::ApiError => e
-    Rails.logger.error "Authentication failed: #{e.message}"
-    redirect_to new_session_path, alert: "Authentication failed. Please try again."
-  end
-end

data/lib/generators/aha_builder_core/authentication/templates/user.rb.erb

@@ -1,8 +0,0 @@
-class User < ApplicationRecord
-  validates :auth_identifier, presence: true, uniqueness: true
-  validates :email, presence: true, uniqueness: true
-
-  def name
-    "#{first_name} #{last_name}".strip.presence || email
-  end
-end