better_auth-rails 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 752aa9b17208fc8152307184bb45d4e36e910ac73d2fee25bfdab567a2eae552
-  data.tar.gz: e5cd67d1e60e41e950beef732238129a840adf596a4d9e70a5e1c44153119bf5
+  metadata.gz: c39998081e1fe16b8a01b980681d982c6acb3d2b6aaf6c748056a952372bc38c
+  data.tar.gz: 128d2b3d19a7ae498182a2e163a3b843e90c018c2a4033aff2c18d5591cae6ab
 SHA512:
-  metadata.gz: ffe3a3fe1c2f7fdeb761532155dd984c0126008928fa79c3e90177be8289805967cdf0a6c370b8b0aff55af997477f7d81769fec0e752a245e6e4baeb7f07e91
-  data.tar.gz: 513fbba0f325cdb0c54c12d790f87018a6bbe7979ade4d91b222fa69ab42c83e2668dd2d0c2a86ed06ea0fe8c67f6042e4b7d30ea20b42a6e07e46367d0f923d
+  metadata.gz: e764e03d032c66031c7ae09e28b671e5600ae9cf1ca0a7d5304064b4aec3b8124c61fdf637dfeafbcd565c63406cdfe82e98b61c823698a96d5ba65645fdac23
+  data.tar.gz: 2f8c7440c4a2a94145fecadda191055c7898d3063d08bb008a3ced7043587ed6ba4a6fe5bf3790552e7ca080cdfceffe7b12b53bd9f058a8a01ba7e604e60d09

data/CHANGELOG.md

@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fixed gemspec files list to use `Dir.glob` instead of `git ls-files` for better CI compatibility
 - Fixed dependency constraints for railties and activesupport (now `>= 6.0, < 9`)
-- Fixed better_auth_rails compatibility gem dependency version
+- Fixed `better_auth_rails` compatibility gem dependency version
 
 ## [0.1.1] - 2026-03-17
 

data/README.md

@@ -7,7 +7,7 @@ Rails adapter for Better Auth Ruby. Provides seamless integration with Ruby on R
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'better_auth-rails'
+gem "better_auth-rails"
 ```
 
 ### Defensive alias package
@@ -29,87 +29,181 @@ bundle install
 Add to your `config/application.rb`:
 
 ```ruby
-require 'better_auth/rails'
+require "better_auth/rails"
 ```
 
 Compatibility require is also supported:
 
 ```ruby
-require 'better_auth_rails'
+require "better_auth_rails"
 ```
 
 Or in your Gemfile:
 
 ```ruby
-gem 'better_auth-rails', require: 'better_auth/rails'
+gem "better_auth-rails", require: "better_auth/rails"
 ```
 
-### Controller Helpers
+### Initializer And Migration
 
-Include the controller helpers in your ApplicationController:
+Create the default initializer and base migration:
 
-```ruby
-class ApplicationController < ActionController::Base
-  include BetterAuth::Rails::ControllerHelpers
-end
+```bash
+bin/rails generate better_auth:install
 ```
 
-Now you have access to authentication methods:
+The same install path is available as a Rails task:
+
+```bash
+bin/rails better_auth:init
+```
+
+To generate only the base migration:
+
+```bash
+bin/rails generate better_auth:migration
+bin/rails better_auth:generate:migration
+```
+
+The generators skip an existing `config/initializers/better_auth.rb` or existing `*_create_better_auth_tables.rb` migration instead of overwriting them.
+
+### Configuration
+
+The install generator creates `config/initializers/better_auth.rb`:
 
 ```ruby
-class PostsController < ApplicationController
-  before_action :authenticate_user!
+BetterAuth::Rails.configure do |config|
+  config.secret =
+    Rails.application.credentials.dig(:better_auth, :secret) ||
+    Rails.application.credentials.secret_key_base ||
+    Rails.application.secret_key_base
+
+  config.base_url = ENV["BETTER_AUTH_URL"]
+  config.base_path = "/api/auth"
+  config.database = ->(options) { BetterAuth::Rails::ActiveRecordAdapter.new(options) }
+  config.trusted_origins = [
+    ENV["BETTER_AUTH_URL"]
+  ].compact
+
+  config.session = {
+    cookie_cache: {
+      enabled: true,
+      max_age: 5 * 60,
+      strategy: "jwe"
+    }
+  }
 
-  def index
-    @posts = current_user.posts
-  end
+  config.advanced = {
+    ip_address: {
+      ip_address_headers: ["x-forwarded-for"],
+      disable_ip_tracking: false
+    }
+  }
 
-  def create
-    @post = current_user.posts.build(post_params)
-    # ...
-  end
+  config.experimental = {
+    joins: false
+  }
+
+  config.social_providers = {
+    # github: BetterAuth::SocialProviders.github(
+    #   client_id: ENV.fetch("GITHUB_CLIENT_ID"),
+    #   client_secret: ENV.fetch("GITHUB_CLIENT_SECRET")
+    # )
+  }
+
+  config.plugins = []
+  config.hooks = {
+    before: [],
+    after: []
+  }
 end
 ```
 
-### Available Methods
+Rails configuration is a thin option builder for the core Rack auth object. The same option concepts are available in core Ruby through `BetterAuth.auth(...)`; Rails places them in `config/initializers/better_auth.rb` so applications can rely on credentials, ActiveRecord, and Rails environment configuration.
 
-- `current_user` - Returns the currently authenticated user
-- `authenticate_user!` - Redirects to login if not authenticated
-- `user_signed_in?` - Returns true if user is authenticated
-- `sign_in(user)` - Signs in a user
-- `sign_out` - Signs out the current user
+The ActiveRecord adapter uses whichever database adapter the Rails app is already configured with, including PostgreSQL and MySQL.
 
-### Configuration
+### JavaScript Client
+
+Ruby Better Auth exposes the same HTTP route surface. Frontend apps should use the upstream Better Auth JavaScript client and point it at the Ruby server:
+
+```ts
+import { createAuthClient } from "better-auth/client";
+
+export const authClient = createAuthClient({
+  baseURL: "http://localhost:3000",
+  basePath: "/api/auth",
+});
+```
 
-Create an initializer `config/initializers/better_auth.rb`:
+Plugin schemas are included in generated migrations through the same configuration:
 
 ```ruby
-BetterAuth.configure do |config|
-  config.secret_key = Rails.application.credentials.secret_key_base
-  config.database_url = Rails.application.credentials.database_url
-  
-  # Optional: Configure session store
-  config.session_store = :redis
-  config.session_options = {
-    url: ENV['REDIS_URL']
-  }
+require "better_auth/api_key"
+
+BetterAuth::Rails.configure do |config|
+  config.plugins = [
+    BetterAuth::Plugins.api_key
+  ]
 end
+
+# Then regenerate before migrating if this is a new app:
+# bin/rails generate better_auth:migration
 ```
 
 ### Routes
 
-Mount the Better Auth engine in your routes:
+Mount the Better Auth Rack app in your routes:
+
+```ruby
+Rails.application.routes.draw do
+  better_auth
+end
+```
+
+By default this mounts at `/api/auth`. Rails mounts the core Rack auth app through a small wrapper so Better Auth still sees the full auth path after Rails moves the mount prefix into `SCRIPT_NAME`. To customize the path:
 
 ```ruby
 Rails.application.routes.draw do
-  mount BetterAuth::Rails::Engine => '/auth'
-  
-  # Your routes...
+  better_auth at: "/auth"
 end
 ```
 
+The Better Auth core router handles internal routes such as `/callback/:providerId`.
+
+### Controller Helpers
+
+Include the controller helpers in your ApplicationController:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include BetterAuth::Rails::ControllerHelpers
+end
+```
+
+Now you have access to authentication methods:
+
+```ruby
+class PostsController < ApplicationController
+  before_action :require_authentication
+
+  def index
+    @user = current_user
+  end
+end
+```
+
+### Available Methods
+
+- `current_session` - Returns the current Better Auth session hash
+- `current_user` - Returns the current Better Auth user hash
+- `authenticated?` - Returns true when a user is present
+- `require_authentication` - Halts with `head :unauthorized` and returns `false` when no user is present
+
 ## Development
 
+Full documentation is being adapted in the root [`docs/`](/Users/sebastiansala/projects/better-auth/docs/README.md) app. The Rails guide lives at `docs/content/docs/integrations/rails.mdx`; pages with a Ruby port warning still contain upstream TypeScript examples for reference.
+
 ### Setup
 
 ```bash
@@ -125,13 +219,13 @@ bundle install
 
 ```bash
 # Run all tests
-bundle exec rspec
+rbenv exec bundle exec rspec
 
 # Run with coverage
-COVERAGE=true bundle exec rspec
+COVERAGE=true rbenv exec bundle exec rspec
 
 # Run specific test
-bundle exec rspec spec/better_auth/rails/controller_helpers_spec.rb
+rbenv exec bundle exec rspec spec/better_auth/rails/controller_helpers_spec.rb
 ```
 
 ### Code Style
@@ -140,10 +234,10 @@ We use StandardRB for linting:
 
 ```bash
 # Check style
-bundle exec standardrb
+RUBOCOP_CACHE_ROOT=/private/var/folders/7x/jrsz946d2w73n42fb1_ff5000000gn/T/rubocop_cache_rails rbenv exec bundle exec standardrb
 
 # Auto-fix issues
-bundle exec standardrb --fix
+RUBOCOP_CACHE_ROOT=/private/var/folders/7x/jrsz946d2w73n42fb1_ff5000000gn/T/rubocop_cache_rails rbenv exec bundle exec standardrb --fix
 ```
 
 ## Contributing

data/lib/better_auth/rails/active_record_adapter.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    class ActiveRecordAdapter < BetterAuth::Adapters::Base
+      begin
+        require "active_record" unless defined?(::ActiveRecord)
+      rescue LoadError
+        # ActiveRecord is required only when the adapter is instantiated in a Rails app.
+      end
+
+      if defined?(::ActiveRecord::Base)
+        class ApplicationRecord < ::ActiveRecord::Base
+          self.abstract_class = true
+        end
+      else
+        class ApplicationRecord
+        end
+      end
+
+      attr_reader :connection
+
+      def initialize(options, connection: nil)
+        super(options)
+        @connection = connection || ::ActiveRecord::Base
+        @models = {}
+      end
+
+      def create(model:, data:, force_allow_id: false)
+        model = model.to_s
+        input = transform_input(model, data, "create", force_allow_id)
+        record = model_class(model).create!(physical_attributes(model, input))
+        normalize_record(model, record)
+      end
+
+      def find_one(model:, where: [], select: nil, join: nil)
+        find_many(model: model, where: where, select: select, join: join, limit: 1).first
+      end
+
+      def find_many(model:, where: [], sort_by: nil, limit: nil, offset: nil, select: nil, join: nil)
+        model = model.to_s
+        relation = relation_for(model, where: where, sort_by: sort_by, limit: limit, offset: offset, select: select, join: join)
+        records = relation.map { |record| normalize_record(model, record, join: join) }
+        collection_join?(model, join) ? aggregate_collection_joins(records) : records
+      end
+
+      def update(model:, where:, update:)
+        model = model.to_s
+        record = relation_for(model, where: where).first
+        return nil unless record
+
+        record.update!(physical_attributes(model, transform_input(model, update, "update", true)))
+        normalize_record(model, record)
+      end
+
+      def update_many(model:, where:, update:, returning: false)
+        model = model.to_s
+        attributes = physical_attributes(model, transform_input(model, update, "update", true))
+        relation = relation_for(model, where: where)
+        if returning
+          relation.map do |record|
+            record.update!(attributes)
+            normalize_record(model, record)
+          end
+        else
+          relation.update_all(attributes)
+        end
+      end
+
+      def delete(model:, where:)
+        model = model.to_s
+        record = relation_for(model, where: where).first
+        record&.destroy!
+        nil
+      end
+
+      def delete_many(model:, where:)
+        relation_for(model.to_s, where: where).delete_all
+      end
+
+      def count(model:, where: nil)
+        relation_for(model.to_s, where: where || []).count
+      end
+
+      def transaction
+        connection.connection.transaction { yield self }
+      end
+
+      private
+
+      def model_class(model)
+        model = model.to_s
+        return @models[model] if @models.key?(model)
+
+        klass = Class.new(ApplicationRecord)
+        model_namespace.const_set(class_name_for(model), klass)
+        klass.table_name = table_for(model) if klass.respond_to?(:table_name=)
+        klass.primary_key = storage_field(model, "id") if klass.respond_to?(:primary_key=)
+        @models[model] = klass
+        define_join_associations(model, klass)
+        klass
+      end
+
+      def relation_for(model, where:, sort_by: nil, limit: nil, offset: nil, select: nil, join: nil)
+        relation = model_class(model).all
+        relation = apply_where(model, relation, where || [])
+        relation = apply_select(model, relation, select) if select
+        relation = apply_join_includes(model, relation, join) if join
+        relation = apply_order(model, relation, sort_by) if sort_by
+        relation = relation.limit(Integer(limit)) if limit
+        relation = relation.offset(Integer(offset)) if offset
+        relation
+      end
+
+      def apply_where(model, relation, where)
+        Array(where).reduce(relation) do |scope, clause|
+          field = storage_key(fetch_key(clause, :field))
+          column = storage_field(model, field)
+          operator = (fetch_key(clause, :operator) || "eq").to_s
+          value = fetch_key(clause, :value)
+          apply_operator(scope, column, operator, value)
+        end
+      end
+
+      def apply_operator(scope, column, operator, value)
+        case operator
+        when "in" then scope.where(column => Array(value))
+        when "not_in" then scope.where.not(column => Array(value))
+        when "ne" then scope.where.not(column => value)
+        when "gt" then scope.where("#{column} > ?", value)
+        when "gte" then scope.where("#{column} >= ?", value)
+        when "lt" then scope.where("#{column} < ?", value)
+        when "lte" then scope.where("#{column} <= ?", value)
+        when "contains" then scope.where("#{column} LIKE ?", "%#{value}%")
+        when "starts_with" then scope.where("#{column} LIKE ?", "#{value}%")
+        when "ends_with" then scope.where("#{column} LIKE ?", "%#{value}")
+        else scope.where(column => value)
+        end
+      end
+
+      def apply_select(model, relation, select)
+        columns = Array(select).map { |field| storage_field(model, storage_key(field)) }
+        relation.select(*columns)
+      end
+
+      def apply_order(model, relation, sort_by)
+        field = storage_key(fetch_key(sort_by, :field))
+        direction = (fetch_key(sort_by, :direction).to_s.downcase == "desc") ? :desc : :asc
+        relation.order(storage_field(model, field) => direction)
+      end
+
+      def transform_input(model, data, action, force_allow_id)
+        fields = schema_for(model).fetch(:fields)
+        input = stringify_keys(data)
+        output = {}
+        fields.each do |field, attributes|
+          next if field == "id" && input.key?(field) && !force_allow_id
+
+          value_provided = input.key?(field)
+          value = input[field]
+          if !value_provided && action == "create" && attributes.key?(:default_value)
+            value = resolve_default(attributes[:default_value])
+            value_provided = true
+          elsif !value_provided && action == "update" && attributes[:on_update]
+            value = resolve_default(attributes[:on_update])
+            value_provided = true
+          end
+          output[field] = value if value_provided
+        end
+        output["id"] = SecureRandom.urlsafe_base64(16) if action == "create" && !output.key?("id")
+        output
+      end
+
+      def physical_attributes(model, logical)
+        logical.each_with_object({}) do |(field, value), attributes|
+          attributes[storage_field(model, field)] = value
+        end
+      end
+
+      def normalize_record(model, record, join: nil)
+        return nil unless record
+
+        attributes = record.respond_to?(:attributes) ? record.attributes : record
+        normalized = schema_for(model).fetch(:fields).each_with_object({}) do |(field, config), output|
+          column = config[:field_name] || physical_name(field)
+          output[field] = attributes[column] if attributes.key?(column)
+        end
+        attach_joins(model, normalized, record, join)
+      end
+
+      def attach_joins(model, normalized, record, join)
+        return normalized unless join
+
+        join.each_key do |join_model|
+          join_model = join_model.to_s
+          definition = join_definition(model, join_model)
+          next unless definition
+
+          association = definition.fetch(:association)
+          next unless record.respond_to?(association)
+
+          joined = record.public_send(association)
+          normalized[join_model] = if definition[:collection]
+            Array(joined).map { |joined_record| normalize_record(join_model, joined_record) }
+          else
+            normalize_record(join_model, joined)
+          end
+        end
+        normalized
+      end
+
+      def apply_join_includes(model, relation, join)
+        associations = join.filter_map do |join_model, _enabled|
+          join_definition(model, join_model.to_s)&.fetch(:association)
+        end
+        return relation if associations.empty? || !relation.respond_to?(:includes)
+
+        relation.includes(*associations)
+      end
+
+      def define_join_associations(model, klass)
+        case model
+        when "session", "account"
+          return unless klass.respond_to?(:belongs_to)
+
+          klass.belongs_to(
+            :user,
+            class_name: model_class("user").name,
+            foreign_key: storage_field(model, "userId"),
+            primary_key: storage_field("user", "id"),
+            optional: true
+          )
+        when "user"
+          return unless klass.respond_to?(:has_many)
+
+          klass.has_many(
+            :accounts,
+            class_name: model_class("account").name,
+            foreign_key: storage_field("account", "userId"),
+            primary_key: storage_field("user", "id")
+          )
+        end
+      end
+
+      def join_definition(model, join_model)
+        case [model.to_s, join_model.to_s]
+        when ["session", "user"], ["account", "user"]
+          {association: :user, collection: false}
+        when ["user", "account"]
+          {association: :accounts, collection: true}
+        end
+      end
+
+      def model_namespace
+        @model_namespace ||= BetterAuth::Rails.const_set("ActiveRecordAdapterModels#{object_id}", Module.new)
+      end
+
+      def class_name_for(model)
+        physical_name(model).split("_").map(&:capitalize).join
+      end
+
+      def collection_join?(model, join)
+        model == "user" && join&.keys&.any? { |join_model| join_model.to_s == "account" }
+      end
+
+      def aggregate_collection_joins(records)
+        records
+      end
+
+      def table_for(model)
+        schema_for(model).fetch(:model_name)
+      end
+
+      def schema_for(model)
+        BetterAuth::Schema.auth_tables(options).fetch(model.to_s)
+      end
+
+      def storage_field(model, field)
+        schema_for(model).fetch(:fields).fetch(field.to_s).fetch(:field_name, physical_name(field))
+      end
+
+      def stringify_keys(value)
+        return {} unless value.respond_to?(:each)
+
+        value.each_with_object({}) { |(key, object), result| result[storage_key(key)] = object }
+      end
+
+      def fetch_key(hash, key)
+        hash[key] || hash[key.to_s] || hash[storage_key(key)] || hash[storage_key(key).to_sym]
+      end
+
+      def storage_key(value)
+        BetterAuth::Schema.send(:storage_key, value)
+      end
+
+      def physical_name(value)
+        BetterAuth::Schema.send(:physical_name, value)
+      end
+
+      def resolve_default(value)
+        value.respond_to?(:call) ? value.call : value
+      end
+    end
+  end
+end

data/lib/better_auth/rails/configuration.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    class Configuration
+      AUTH_OPTION_NAMES = %i[
+        app_name
+        base_url
+        base_path
+        secret
+        database
+        plugins
+        trusted_origins
+        rate_limit
+        session
+        account
+        user
+        verification
+        advanced
+        email_and_password
+        password_hasher
+        email_verification
+        social_providers
+        experimental
+        secondary_storage
+        database_hooks
+        hooks
+        on_api_error
+        disabled_paths
+        logger
+      ].freeze
+
+      attr_accessor(*AUTH_OPTION_NAMES)
+
+      def initialize
+        @base_path = BetterAuth::Configuration::DEFAULT_BASE_PATH
+        @plugins = []
+        @trusted_origins = []
+        @database = ->(options) { ActiveRecordAdapter.new(options) }
+      end
+
+      def to_auth_options
+        AUTH_OPTION_NAMES.each_with_object({}) do |name, options|
+          value = public_send(name)
+          next if value.nil?
+          next if value.respond_to?(:empty?) && value.empty?
+
+          options[name] = value
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/rails/controller_helpers.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    module ControllerHelpers
+      def current_session
+        data = better_auth_session_data
+        data&.fetch(:session, nil) || data&.fetch("session", nil)
+      end
+
+      def current_user
+        data = better_auth_session_data
+        data&.fetch(:user, nil) || data&.fetch("user", nil)
+      end
+
+      def authenticated?
+        !current_user.nil?
+      end
+
+      def require_authentication
+        return true if authenticated?
+
+        head(:unauthorized) if respond_to?(:head)
+        false
+      end
+
+      private
+
+      def better_auth_session_data
+        return request.env["better_auth.session"] if request.env.key?("better_auth.session")
+
+        request.env["better_auth.session"] = resolve_better_auth_session
+      end
+
+      def resolve_better_auth_session
+        context = BetterAuth::Endpoint::Context.new(
+          path: request.path,
+          method: request.request_method,
+          query: request.query_parameters,
+          body: {},
+          params: {},
+          headers: {"cookie" => request.get_header("HTTP_COOKIE")},
+          context: BetterAuth::Rails.auth.context,
+          request: request
+        )
+        BetterAuth::Session.find_current(context, disable_refresh: true)
+      end
+    end
+  end
+end

data/lib/better_auth/rails/migration.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    module Migration
+      module_function
+
+      def render(options, migration_version: nil)
+        migration_version ||= self.migration_version
+        tables = BetterAuth::Schema.auth_tables(options)
+        lines = [
+          "# frozen_string_literal: true",
+          "",
+          "class CreateBetterAuthTables < ActiveRecord::Migration[#{migration_version}]",
+          "  def change"
+        ]
+        tables.each_value { |table| lines.concat(create_table_lines(table)) }
+        tables.each_value { |table| lines.concat(primary_key_lines(table)) }
+        tables.each_value { |table| lines.concat(index_lines(table)) }
+        tables.each_value { |table| lines.concat(foreign_key_lines(table, options)) }
+        lines.concat(["  end", "end", ""])
+        lines.join("\n")
+      end
+
+      def migration_version
+        return ::ActiveRecord::Migration.current_version if defined?(::ActiveRecord::Migration)
+
+        "7.0"
+      end
+
+      def create_table_lines(table)
+        table_name = table.fetch(:model_name)
+        lines = ["", "    create_table :#{table_name}, id: false do |t|"]
+        table.fetch(:fields).each do |logical_field, attributes|
+          lines << column_line(logical_field, attributes)
+        end
+        lines << "    end"
+      end
+
+      def column_line(logical_field, attributes)
+        column = attributes[:field_name] || physical_name(logical_field)
+        parts = ["t.#{rails_type(attributes)} :#{column}"]
+        parts << "null: false" if attributes[:required]
+        default = default_value(attributes)
+        parts << "default: #{default}" unless default.nil?
+        "      #{parts.join(", ")}"
+      end
+
+      def index_lines(table)
+        table_name = table.fetch(:model_name)
+        table.fetch(:fields).filter_map do |logical_field, attributes|
+          next unless attributes[:unique] || attributes[:index]
+
+          column = attributes[:field_name] || physical_name(logical_field)
+          unique = attributes[:unique] ? ", unique: true" : ""
+          "    add_index :#{table_name}, :#{column}#{unique}"
+        end
+      end
+
+      def primary_key_lines(table)
+        table_name = table.fetch(:model_name)
+        return [] unless table.fetch(:fields).key?("id")
+
+        [
+          %(    execute "ALTER TABLE \#{quote_table_name(:#{table_name})} ADD PRIMARY KEY (\#{quote_column_name(:id)})")
+        ]
+      end
+
+      def foreign_key_lines(table, options)
+        table_name = table.fetch(:model_name)
+        table.fetch(:fields).filter_map do |logical_field, attributes|
+          reference = attributes[:references]
+          next unless reference
+
+          column = attributes[:field_name] || physical_name(logical_field)
+          target = foreign_key_target(reference.fetch(:model), options)
+          on_delete = reference[:on_delete] ? ", on_delete: :#{reference[:on_delete]}" : ""
+          "    add_foreign_key :#{table_name}, :#{target}, column: :#{column}#{on_delete}"
+        end
+      end
+
+      def rails_type(attributes)
+        case attributes[:type]
+        when "boolean" then "boolean"
+        when "date" then "datetime"
+        when "number" then attributes[:bigint] ? "bigint" : "integer"
+        else "string"
+        end
+      end
+
+      def default_value(attributes)
+        default = attributes[:default_value]
+        return if default.respond_to?(:call)
+
+        case default
+        when true then "true"
+        when false then "false"
+        when Numeric then default.to_s
+        when String then default.inspect
+        end
+      end
+
+      def physical_name(value)
+        BetterAuth::Schema.send(:physical_name, value)
+      end
+
+      def foreign_key_target(model, options)
+        BetterAuth::Schema.auth_tables(options).fetch(model.to_s, nil)&.fetch(:model_name) || model
+      end
+    end
+  end
+end

data/lib/better_auth/rails/mounted_app.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    class MountedApp
+      def initialize(auth, mount_path:)
+        @auth = auth
+        @mount_path = normalize_path(mount_path)
+      end
+
+      def call(env)
+        @auth.call(env.merge("PATH_INFO" => mounted_path_info(env)))
+      end
+
+      private
+
+      def mounted_path_info(env)
+        path_info = normalize_path(env["PATH_INFO"])
+        script_name = normalize_path(env["SCRIPT_NAME"])
+        prefix = (script_name == "/") ? @mount_path : script_name
+
+        return path_info if path_info == prefix || path_info.start_with?("#{prefix}/")
+
+        normalize_path("#{prefix}/#{path_info.delete_prefix("/")}")
+      end
+
+      def normalize_path(path)
+        normalized = path.to_s
+        normalized = "/#{normalized}" unless normalized.start_with?("/")
+        normalized = normalized.squeeze("/")
+        normalized = normalized.delete_suffix("/") unless normalized == "/"
+        normalized.empty? ? "/" : normalized
+      end
+    end
+  end
+end

data/lib/better_auth/rails/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "better_auth_rails.routes" do
+        ActiveSupport.on_load(:action_dispatch_routing) do
+          include BetterAuth::Rails::Routing
+        end
+      end
+
+      rake_tasks do
+        load File.expand_path("../../tasks/better_auth.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/better_auth/rails/routing.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Rails
+    module Routing
+      def better_auth(auth: nil, at: BetterAuth::Configuration::DEFAULT_BASE_PATH)
+        mount_path = normalize_better_auth_mount_path(at)
+        auth ||= BetterAuth::Rails.auth(base_path: mount_path)
+        mount BetterAuth::Rails::MountedApp.new(auth, mount_path: mount_path), at: mount_path
+      end
+
+      private
+
+      def normalize_better_auth_mount_path(path)
+        normalized = path.to_s
+        normalized = "/#{normalized}" unless normalized.start_with?("/")
+        normalized = normalized.squeeze("/")
+        (normalized == "/") ? normalized : normalized.delete_suffix("/")
+      end
+    end
+  end
+end

data/lib/better_auth/rails/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module Rails
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/lib/better_auth/rails.rb

@@ -1,10 +1,33 @@
 # frozen_string_literal: true
 
+require "better_auth"
 require_relative "rails/version"
+require_relative "rails/configuration"
+require_relative "rails/migration"
+require_relative "rails/active_record_adapter"
+require_relative "rails/mounted_app"
+require_relative "rails/routing"
+require_relative "rails/controller_helpers"
+require_relative "rails/railtie" if defined?(::Rails::Railtie)
 
 module BetterAuth
   module Rails
-    # Rails-specific authentication adapters
-    # Provides middleware, controller helpers, and generators
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+        @auth = nil
+      end
+
+      def auth(overrides = nil)
+        options = configuration.to_auth_options
+        return @auth ||= BetterAuth.auth(options) if overrides.nil? || overrides.empty?
+
+        BetterAuth.auth(options.merge(overrides))
+      end
+    end
   end
 end

data/lib/generators/better_auth/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "better_auth/rails"
+require "generators/better_auth/migration/migration_generator"
+
+module BetterAuth
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      class_option :database, type: :string, default: "active_record"
+
+      def create_initializer
+        initializer = "config/initializers/better_auth.rb"
+        if File.exist?(destination_path(initializer))
+          say_status :skip, "#{initializer} already exists"
+          return
+        end
+
+        template "initializer.rb.tt", initializer
+      end
+
+      def create_migration
+        MigrationGenerator.start([], destination_root: destination_root)
+      end
+
+      private
+
+      def destination_path(path)
+        File.join(destination_root, path)
+      end
+    end
+  end
+end

data/lib/generators/better_auth/install/templates/initializer.rb.tt

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+BetterAuth::Rails.configure do |config|
+  config.secret =
+    Rails.application.credentials.dig(:better_auth, :secret) ||
+    Rails.application.credentials.secret_key_base ||
+    Rails.application.secret_key_base
+
+  config.base_url = ENV["BETTER_AUTH_URL"]
+  config.base_path = "/api/auth"
+  config.database = ->(options) { BetterAuth::Rails::ActiveRecordAdapter.new(options) }
+  config.trusted_origins = [
+    ENV["BETTER_AUTH_URL"]
+  ].compact
+
+  config.session = {
+    cookie_cache: {
+      enabled: true,
+      max_age: 5 * 60,
+      strategy: "jwe"
+    }
+  }
+
+  config.advanced = {
+    ip_address: {
+      ip_address_headers: ["x-forwarded-for"],
+      disable_ip_tracking: false
+    }
+  }
+
+  config.experimental = {
+    joins: false
+  }
+
+  config.social_providers = {
+    # github: BetterAuth::SocialProviders.github(
+    #   client_id: ENV.fetch("GITHUB_CLIENT_ID"),
+    #   client_secret: ENV.fetch("GITHUB_CLIENT_SECRET")
+    # )
+  }
+
+  # Add Better Auth plugins here.
+  config.plugins = []
+
+  # Add Better Auth hooks here. Auth decisions still run through the core gem.
+  config.hooks = {
+    before: [],
+    after: []
+  }
+end

data/lib/generators/better_auth/migration/migration_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "better_auth/rails"
+
+module BetterAuth
+  module Generators
+    class MigrationGenerator < ::Rails::Generators::Base
+      def create_migration
+        if existing_migration?
+          say_status :skip, "db/migrate/*_create_better_auth_tables.rb already exists"
+          return
+        end
+
+        create_file migration_path, BetterAuth::Rails::Migration.render(generator_config)
+      end
+
+      private
+
+      def existing_migration?
+        Dir[File.join(destination_root, "db/migrate/*_create_better_auth_tables.rb")].any?
+      end
+
+      def migration_path
+        File.join("db/migrate", "#{timestamp}_create_better_auth_tables.rb")
+      end
+
+      def timestamp
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def generator_config
+        options = BetterAuth::Rails.configuration.to_auth_options
+        options[:secret] ||= BetterAuth::Configuration::DEFAULT_SECRET
+        options[:database] ||= :memory
+        BetterAuth::Configuration.new(options)
+      end
+    end
+  end
+end

data/lib/tasks/better_auth.rake

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+namespace :better_auth do
+  desc "Create the Better Auth initializer and base migration"
+  task :init do
+    require "generators/better_auth/install/install_generator"
+    BetterAuth::Generators::InstallGenerator.start([])
+  end
+
+  namespace :generate do
+    desc "Create the Better Auth base migration"
+    task :migration do
+      require "generators/better_auth/migration/migration_generator"
+      BetterAuth::Generators::MigrationGenerator.start([])
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Sebastian Sala
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: better_auth
@@ -64,6 +63,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -134,6 +153,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 description: Rails integration for Better Auth Ruby. Provides middleware, controller
   helpers, and generators.
 email:
@@ -146,8 +179,19 @@ files:
 - LICENSE.md
 - README.md
 - lib/better_auth/rails.rb
+- lib/better_auth/rails/active_record_adapter.rb
+- lib/better_auth/rails/configuration.rb
+- lib/better_auth/rails/controller_helpers.rb
+- lib/better_auth/rails/migration.rb
+- lib/better_auth/rails/mounted_app.rb
+- lib/better_auth/rails/railtie.rb
+- lib/better_auth/rails/routing.rb
 - lib/better_auth/rails/version.rb
 - lib/better_auth_rails.rb
+- lib/generators/better_auth/install/install_generator.rb
+- lib/generators/better_auth/install/templates/initializer.rb.tt
+- lib/generators/better_auth/migration/migration_generator.rb
+- lib/tasks/better_auth.rake
 homepage: https://github.com/sebasxsala/better-auth
 licenses:
 - MIT
@@ -156,7 +200,6 @@ metadata:
   source_code_uri: https://github.com/sebasxsala/better-auth
   changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth-rails/CHANGELOG.md
   bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -171,8 +214,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails adapter for Better Auth
 test_files: []