better_auth 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2ba3cc27f9b1ebc6cb35de7a95a10351c30f5523de796c82b7c90773d663381
+  data.tar.gz: 81b03e1d625d242adc6255806b7651cebee65f59179110aae7df85b7beab426f
+SHA512:
+  metadata.gz: 61a29dc835cd5758628b358153888cc78eb721795cd286e55210c920766129826d08b5bbdf2fe9a049df56b3d6a9d4bd8f33c82b067bde77c812c87738af94e2
+  data.tar.gz: 18d543129a8577e9974ce0887db187e837ff2b9175cce97efd33a6afba615f1d34272fb193a0008694c63c998b12740ed6c2490ecb765ad9b24f131be389a250

data/.ruby-version

@@ -0,0 +1 @@
+3.3.10

data/.standard.yml

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# StandardRB Configuration
+# https://github.com/standardrb/standard
+
+ignore:
+  - 'vendor/**/*'
+  - 'node_modules/**/*'
+  - 'tmp/**/*'
+  - 'coverage/**/*'
+  - 'doc/**/*'
+  - 'pkg/**/*'

data/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "rubyLsp.enabled": true,
+  "rubyLsp.formatter": "standard",
+  "rubyLsp.linters": ["standard"],
+  "editor.formatOnSave": true,
+  "editor.insertSpaces": true,
+  "editor.tabSize": 2,
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "[ruby]": {
+    "editor.defaultFormatter": "Shopify.ruby-lsp",
+    "editor.formatOnSave": true,
+    "editor.rulers": [120]
+  },
+  "search.exclude": {
+    "**/.bundle": true,
+    "**/vendor": true,
+    "**/coverage": true,
+    "**/doc": true,
+    "**/*.gem": true
+  }
+}

data/AGENTS.md

@@ -0,0 +1,50 @@
+# AGENTS.md - Better Auth Core Package
+
+**⚠️ CRITICAL: Always read this file when editing files in packages/better_auth/**
+
+## What is this package?
+
+This is the **core gem** of Better Auth Ruby - a Ruby port of the TypeScript [better-auth](https://github.com/better-auth/better-auth) library. It contains framework-agnostic authentication logic built on Rack.
+
+## Upstream Reference
+
+**Always check `upstream/` before implementing or modifying features.**
+
+The TypeScript implementation in `upstream/packages/better-auth/` is the source of truth. Your workflow should be:
+
+1. **Find the feature** in `upstream/packages/better-auth/src/`
+2. **Understand how it works** in TypeScript
+3. **Translate to Ruby** following Ruby/Rails best practices
+4. **Adapt idiomatically** - don't do a literal translation, make it feel native to Ruby
+
+Key upstream directories:
+- `upstream/packages/better-auth/src/` - Core auth logic
+- `upstream/packages/better-auth/src/plugins/` - Plugin implementations
+
+## Development Commands
+
+```bash
+bundle install          # Install dependencies
+bundle exec rake test   # Run tests (Minitest)
+bundle exec standardrb  # Run linter
+bundle exec standardrb --fix  # Fix linting issues
+```
+
+## Directory Structure
+
+* `lib/better_auth.rb` - Main entry point
+* `lib/better_auth/core/` - Core authentication logic
+* `test/` - Tests (Minitest)
+
+## Code Style
+
+* StandardRB for linting
+* `frozen_string_literal: true` in all files
+* snake_case for files/methods, CamelCase for classes
+
+## After Everything is Done
+
+**Unless the user asked for it, DO NOT COMMIT**
+
+* Make sure `bundle exec standardrb` passes
+* Make sure `bundle exec rake test` passes

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial project setup
+- Basic gem structure
+- StandardRB configuration
+- Minitest for core testing
+- RSpec for Rails adapter testing
+- CI/CD workflows for GitHub Actions

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,173 @@
+# Contributor Covenant 3.0
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the
+dignity, rights, and contributions of all individuals, regardless of
+characteristics including race, ethnicity, caste, color, age, physical
+characteristics, neurodiversity, disability, sex or gender, gender identity or
+expression, sexual orientation, language, philosophy or religion, national or
+social origin, socio-economic position, level of education, or other status.
+The same privileges of participation are extended to everyone who participates
+in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our
+community's expectations for positive behavior.
+We also understand that our words and actions may be interpreted differently
+than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each
+other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of
+   gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our
+   community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community.
+Instances, threats, and promotion of these behaviors are violations of this Code
+of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in
+   unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments
+   directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone's personality or
+   behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered
+   inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or
+   private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm
+   toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or
+   pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content
+   you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a
+   way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which
+   includes, links or describes any other restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their
+best to collaborate.
+
+Not every conflict represents a code of conduct violation, and this Code of
+Conduct reinforces encouraged behaviors and norms that can help avoid conflicts
+and minimize harm.
+
+When an incident does occur, it is important to report it promptly.
+To report a possible violation, **email [community@better-auth.com](mailto:community@better-auth.com)**
+
+Community Moderators take reports of violations seriously and will make every
+effort to respond in a timely manner.
+
+They will investigate all reports of code of conduct violations, reviewing
+messages, logs, and recordings, or interviewing witnesses and other
+participants.
+
+Community Moderators will keep investigation and enforcement actions as
+transparent as possible while prioritizing safety and confidentiality.
+
+In order to honor these values, enforcement actions are carried out in private
+with the involved parties, but communicating to the whole community may be part
+of a mutually agreed upon resolution.
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct
+has been violated, the following enforcement ladder may be used to determine how
+best to repair harm, based on the incident's impact on the individuals involved
+and the community as a whole.
+Depending on the severity of a violation, lower rungs on the ladder may be
+skipped.
+
+1. Warning
+   1. Event: A violation involving a single incident or series of incidents.
+   2. Consequence: A private, written warning from the Community Moderators.
+   3. Repair: Examples of repair include a private written apology,
+      acknowledgement of responsibility, and seeking clarification on
+      expectations.
+2. Temporarily Limited Activities
+   1. Event: A repeated incidence of a violation that previously resulted in a
+      warning, or the first incidence of a more serious violation.
+   2. Consequence: A private, written warning with a time-limited cooldown
+      period designed to underscore the seriousness of the situation and give
+      the community members involved time to process the incident.
+      The cooldown period may be limited to particular communication channels or
+      interactions with particular community members.
+   3. Repair: Examples of repair may include making an apology, using the
+      cooldown period to reflect on actions and impact, and being thoughtful
+      about re-entering community spaces after the period is over.
+3. Temporary Suspension
+   1. Event: A pattern of repeated violation which the Community Moderators have
+      tried to address with warnings, or a single serious violation.
+   2. Consequence: A private written warning with conditions for return from
+      suspension.
+      In general, temporary suspensions give the person being suspended time to
+      reflect upon their behavior and possible corrective actions.
+   3. Repair: Examples of repair include respecting the spirit of the
+      suspension, meeting the specified conditions for return, and being
+      thoughtful about how to reintegrate with the community when the suspension
+      is lifted.
+4. Permanent Ban
+   1. Event: A pattern of repeated code of conduct violations that other steps
+      on the ladder have failed to resolve, or a violation so serious that the
+      Community Moderators determine there is no way to keep the community safe
+      with this person as a member.
+   2. Consequence: Access to all community spaces, tools, and communication
+      channels is removed.
+      In general, permanent bans should be rarely used, should have strong
+      reasoning behind them, and should only be resorted to if working through
+      other remedies has failed to change the behavior.
+   3. Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline.
+It does not limit the ability of Community Managers to use their discretion and
+judgment, in keeping with the best interests of our community.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public or other
+spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0,
+permanently available at
+[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and
+licensed under CC BY-SA 4.0.
+To view a copy of this license, visit
+[https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq).
+Translations are provided at
+[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
+Additional enforcement and community guideline resources can be found at
+[https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources).
+The enforcement ladder was inspired by the work of
+[Mozilla's code of conduct team](https://github.com/mozilla/inclusion).

data/CONTRIBUTING.md

@@ -0,0 +1,187 @@
+# Contributing to Better Auth Ruby
+
+Thank you for your interest in contributing to Better Auth Ruby!
+This guide will help you get started with the contribution process.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our
+[Code of Conduct](/CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code.
+
+## Project Structure
+
+```
+lib/
+  better_auth.rb              # Main entry point
+  better_auth/
+    version.rb                # Version constant
+    core.rb                   # Core module loader
+    core/                     # Core authentication logic
+    rails.rb                  # Rails adapter entry
+    rails/                    # Rails-specific code
+
+test/                       # Core library tests (Minitest)
+spec/                       # Rails adapter tests (RSpec)
+```
+
+## Development Guidelines
+
+When contributing to Better Auth Ruby:
+
+* Keep changes focused. Large PRs are harder to review.
+* Follow Ruby conventions and idioms
+* Ensure all code passes StandardRB linting
+* Write tests for new features
+* Maintain backward compatibility when possible
+
+## Getting Started
+
+1. Fork the repository to your GitHub account
+
+2. Clone your fork locally:
+
+   ```bash
+   git clone https://github.com/your-username/better-auth-ruby.git
+   cd better-auth-ruby
+   ```
+
+3. Install Ruby (3.2+ required, 3.3 recommended)
+
+   We recommend using a Ruby version manager like rbenv, rvm, or asdf.
+
+4. Install dependencies:
+
+   ```bash
+   bundle install
+   ```
+
+5. Run tests to ensure everything is working:
+
+   ```bash
+   bundle exec rake ci
+   ```
+
+## Development Workflow
+
+1. Create a new branch for your changes:
+
+   ```bash
+   git checkout -b type/description
+   # Example: git checkout -b feat/oauth-provider
+   ```
+
+   Branch type prefixes:
+
+   * `feat/` - New features
+   * `fix/` - Bug fixes
+   * `docs/` - Documentation changes
+   * `refactor/` - Code refactoring
+   * `test/` - Test-related changes
+   * `chore/` - Build process or tooling changes
+
+2. Make your changes following the code style guidelines
+
+3. Run the linter:
+
+   ```bash
+   bundle exec standardrb --fix
+   ```
+
+4. Add tests for your changes
+
+5. Run the test suite:
+
+   ```bash
+   # Run all tests
+   bundle exec rake ci
+
+   # Run only core tests
+   bundle exec rake test
+
+   # Run only Rails adapter tests
+   bundle exec rspec
+   ```
+
+6. Commit your changes with a descriptive message:
+
+   ```text
+   feat(rails): add current_user helper method
+
+   fix(core): resolve token validation issue
+   ```
+
+7. Push your branch to your fork
+
+8. Open a pull request against the **main** branch
+
+## Code Style
+
+We use [StandardRB](https://github.com/standardrb/standard) for code formatting and linting.
+Before committing, please ensure your code passes:
+
+```bash
+# Check code style
+bundle exec standardrb
+
+# Auto-fix issues
+bundle exec standardrb --fix
+```
+
+### Ruby Style Guidelines
+
+* Use 2 spaces for indentation
+* Use `snake_case` for methods, variables, and file names
+* Use `CamelCase` for classes and modules
+* Use `SCREAMING_SNAKE_CASE` for constants
+* Add `frozen_string_literal: true` pragma to all Ruby files
+* Prefer single quotes for strings without interpolation
+* Avoid unnecessary Ruby features (unless they improve readability)
+
+## Testing Guidelines
+
+### Core Library (Minitest)
+
+Located in `test/` directory:
+
+```ruby
+# test/better_auth/some_feature_test.rb
+require_relative "test_helper"
+
+class SomeFeatureTest < Minitest::Test
+  def test_something
+    assert_equal expected, actual
+  end
+end
+```
+
+### Rails Adapter (RSpec)
+
+Located in `spec/` directory:
+
+```ruby
+# spec/better_auth/rails/some_feature_spec.rb
+require "spec_helper"
+
+RSpec.describe BetterAuth::Rails::SomeFeature do
+  it "does something" do
+    expect(subject).to eq expected
+  end
+end
+```
+
+## Pull Request Process
+
+1. Create a draft pull request early to facilitate discussion
+2. Reference any related issues in your PR description
+3. Ensure all tests pass and the build is successful
+4. Update documentation as needed
+5. Keep your PR focused on a single feature or bug fix
+6. Be responsive to code review feedback
+
+## Security Issues
+
+For security-related issues, please email [security@better-auth.com](mailto:security@better-auth.com).
+Include a detailed description of the vulnerability and steps to reproduce it.
+All reports will be reviewed and addressed promptly.
+For more information, see our [security documentation](/SECURITY.md).

data/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+ruby file: ".ruby-version"
+
+gemspec
+
+group :development, :test do
+  gem "standardrb", "~> 1.0"
+  gem "minitest", "~> 5.25"
+  gem "rake", "~> 13.2"
+  gem "simplecov", "~> 0.22", require: false
+end

data/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2024 - present, Bereket Engida
+
+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/Makefile

@@ -0,0 +1,207 @@
+# Better Auth Ruby - Makefile
+# Este archivo te ayuda a ejecutar comandos comunes de desarrollo
+# Cada comando tiene comentarios explicativos para aprender
+
+# Variables de color para hacer la salida más legible
+BLUE := \033[36m
+GREEN := \033[32m
+YELLOW := \033[33m
+NC := \033[0m # No Color
+
+# =============================================
+# COMANDOS PRINCIPALES DE DESARROLLO
+# =============================================
+
+# Instala todas las dependencias del proyecto
+# Equivale a: bundle install
+.PHONY: install
+install:
+	@echo "$(BLUE)📦 Instalando dependencias...$(NC)"
+	bundle install
+	@echo "$(GREEN)✓ Dependencias instaladas$(NC)"
+
+# Configuración inicial del proyecto (primer clone)
+# Ejecuta bin/setup que hace bundle install
+.PHONY: setup
+setup:
+	@echo "$(BLUE)🔧 Configurando proyecto...$(NC)"
+	bin/setup
+	@echo "$(GREEN)✓ Proyecto configurado$(NC)"
+
+# =============================================
+# COMANDOS DE CALIDAD DE CÓDIGO
+# =============================================
+
+# Revisa que el código cumpla con el estilo StandardRB
+# Muestra errores pero NO los corrige automáticamente
+.PHONY: lint
+lint:
+	@echo "$(BLUE)🔍 Revisando estilo de código...$(NC)"
+	bundle exec standardrb
+	@echo "$(GREEN)✓ Código cumple con el estilo$(NC)"
+
+# Revisa Y AUTOCORRIGE problemas de estilo con StandardRB
+# Úsalo cuando quieras formatear todo automáticamente
+.PHONY: lint-fix
+lint-fix:
+	@echo "$(BLUE)🔧 Corrigiendo estilo de código automáticamente...$(NC)"
+	bundle exec standardrb --fix
+	@echo "$(GREEN)✓ Código corregido$(NC)"
+
+# =============================================
+# COMANDOS DE TESTING
+# =============================================
+
+# Ejecuta TODOS los tests (core + rails adapter)
+# Es lo mismo que: bundle exec rake ci
+.PHONY: test
+test:
+	@echo "$(BLUE)🧪 Ejecutando todos los tests...$(NC)"
+	bundle exec rake test
+	@echo "$(GREEN)✓ Tests completados$(NC)"
+
+# Ejecuta solo los tests del core (Minitest)
+# Son los tests en el directorio test/
+.PHONY: test-core
+test-core:
+	@echo "$(BLUE)🧪 Ejecutando tests del core...$(NC)"
+	bundle exec rake test:core
+	@echo "$(GREEN)✓ Tests del core completados$(NC)"
+
+# Ejecuta solo los tests del adapter Rails (RSpec)
+# Son los tests en el directorio spec/
+.PHONY: test-rails
+test-rails:
+	@echo "$(BLUE)🧪 Ejecutando tests del adapter Rails...$(NC)"
+	bundle exec rspec
+	@echo "$(GREEN)✓ Tests de Rails completados$(NC)"
+
+# Ejecuta tests con cobertura de código
+# Genera reporte en coverage/index.html
+.PHONY: test-coverage
+test-coverage:
+	@echo "$(BLUE)📊 Ejecutando tests con cobertura...$(NC)"
+	COVERAGE=true bundle exec rake test
+	@echo "$(GREEN)✓ Reporte de cobertura en coverage/index.html$(NC)"
+
+# =============================================
+# COMANDOS DE INTEGRACIÓN CONTINUA (CI)
+# =============================================
+
+# Ejecuta TODO el pipeline de CI localmente
+# 1. Lint (StandardRB)
+# 2. Tests (Minitest + RSpec)
+# Esto es lo que corre GitHub Actions en cada PR
+.PHONY: ci
+ci:
+	@echo "$(BLUE)🔧 Ejecutando CI completo...$(NC)"
+	bundle exec rake ci
+	@echo "$(GREEN)✓ CI completado exitosamente$(NC)"
+
+# =============================================
+# COMANDOS DE DESARROLLO INTERACTIVO
+# =============================================
+
+# Abre una consola interactiva (IRB) con la gema cargada
+# Útil para probar código manualmente
+.PHONY: console
+console:
+	@echo "$(BLUE)💻 Abriendo consola interactiva...$(NC)"
+	bin/console
+
+# =============================================
+# COMANDOS DE PUBLICACIÓN (RELEASE)
+# =============================================
+
+# PASO 1: Actualiza la versión en version.rb
+# Debes hacerlo manualmente antes de release
+
+# PASO 2: Crea un git tag con la versión
+# Ejemplo: make tag VERSION=0.1.0
+.PHONY: tag
+tag:
+ifndef VERSION
+	$(error VERSION no está definido. Usa: make tag VERSION=0.1.0)
+endif
+	@echo "$(YELLOW)🏷️  Creando tag v$(VERSION)...$(NC)"
+	git add -A
+	git commit -m "chore: release v$(VERSION)"
+	git tag -a v$(VERSION) -m "Release v$(VERSION)"
+	@echo "$(GREEN)✓ Tag creado. Ahora haz: git push origin main --tags$(NC)"
+
+# PASO 3 (MANUAL): Publica la gema a RubyGems manualmente
+# Solo úsalo si NO estás usando GitHub Actions
+.PHONY: release-manual
+release-manual:
+	@echo "$(YELLOW)📦 Construyendo gema...$(NC)"
+	gem build better_auth.gemspec
+	@echo "$(YELLOW)🚀 Publicando a RubyGems...$(NC)"
+	gem push better_auth-*.gem
+	@echo "$(GREEN)✓ Gema publicada$(NC)"
+
+# =============================================
+# COMANDOS DE BASES DE DATOS (TESTING)
+# =============================================
+
+# Inicia los contenedores de Docker para testing
+# (PostgreSQL, MySQL, Redis)
+.PHONY: db-up
+db-up:
+	@echo "$(BLUE)🐳 Iniciando bases de datos...$(NC)"
+	docker-compose up -d
+	@echo "$(GREEN)✓ Bases de datos listas$(NC)"
+
+# Detiene los contenedores de Docker
+.PHONY: db-down
+db-down:
+	@echo "$(BLUE)🐳 Deteniendo bases de datos...$(NC)"
+	docker-compose down
+	@echo "$(GREEN)✓ Bases de datos detenidas$(NC)"
+
+# =============================================
+# COMANDOS DE LIMPIEZA
+# =============================================
+
+# Limpia archivos temporales y la gema compilada
+.PHONY: clean
+clean:
+	@echo "$(BLUE)🧹 Limpiando archivos temporales...$(NC)"
+	rm -rf *.gem coverage/ .bundle/
+	@echo "$(GREEN)✓ Limpieza completada$(NC)"
+
+# =============================================
+# AYUDA
+# =============================================
+
+# Muestra todos los comandos disponibles con descripción
+.PHONY: help
+help:
+	@echo "$(GREEN)Better Auth Ruby - Comandos disponibles:$(NC)"
+	@echo ""
+	@echo "$(YELLOW)Instalación:$(NC)"
+	@echo "  make install       - Instala dependencias (bundle install)"
+	@echo "  make setup         - Configuración inicial del proyecto"
+	@echo ""
+	@echo "$(YELLOW)Desarrollo:$(NC)"
+	@echo "  make console       - Abre consola interactiva (IRB)"
+	@echo "  make lint          - Revisa estilo de código"
+	@echo "  make lint-fix      - Corrige estilo automáticamente"
+	@echo ""
+	@echo "$(YELLOW)Testing:$(NC)"
+	@echo "  make test          - Ejecuta todos los tests"
+	@echo "  make test-core     - Solo tests del core (Minitest)"
+	@echo "  make test-rails    - Solo tests Rails (RSpec)"
+	@echo "  make test-coverage - Tests con reporte de cobertura"
+	@echo "  make ci            - Ejecuta CI completo (lint + test)"
+	@echo ""
+	@echo "$(YELLOW)Bases de datos (Docker):$(NC)"
+	@echo "  make db-up         - Inicia PostgreSQL, MySQL, Redis"
+	@echo "  make db-down       - Detiene contenedores"
+	@echo ""
+	@echo "$(YELLOW)Release:$(NC)"
+	@echo "  make tag VERSION=x.x.x  - Crea git tag para release"
+	@echo "  make release-manual     - Publica manualmente (NO usar con CI)"
+	@echo ""
+	@echo "$(YELLOW)Utilidades:$(NC)"
+	@echo "  make clean         - Limpia archivos temporales"
+	@echo "  make help          - Muestra esta ayuda"

data/README.md

@@ -0,0 +1,267 @@
+<p align="center">
+  <h2 align="center">
+    Better Auth Ruby
+  </h2>
+
+  <p align="center">
+    The most comprehensive authentication framework for Ruby
+    <br />
+    <a href="https://better-auth.com"><strong>Learn more »</strong></a>
+    <br />
+    <br />
+    <a href="https://discord.gg/better-auth">Discord</a>
+    ·
+    <a href="https://better-auth.com">Website</a>
+    ·
+    <a href="https://github.com/sebasxsala/better-auth/issues">Issues</a>
+  </p>
+
+[![Gem](https://img.shields.io/gem/v/better_auth?style=flat&colorA=000000&colorB=000000)](https://rubygems.org/gems/better_auth)
+[![GitHub stars](https://img.shields.io/github/stars/sebasxsala/better-auth?style=flat&colorA=000000&colorB=000000)](https://github.com/sebasxsala/better-auth/stargazers)
+</p>
+
+## About the Project
+
+Better Auth Ruby is a comprehensive authentication and authorization library for Ruby. It provides a complete set of features out of the box and includes a plugin ecosystem that simplifies adding advanced functionalities with minimal code.
+
+### Features
+
+- **Framework Agnostic Core**: Works with any Rack-based application
+- **Rails Integration**: First-class Rails support with middleware and helpers
+- **Session Management**: Secure session handling
+- **Multiple Authentication Methods**: Email/password, OAuth, JWT, and more
+- **Two-Factor Authentication**: TOTP and WebAuthn support
+- **Plugin System**: Extensible architecture for custom features
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_auth'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install better_auth
+```
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require 'better_auth'
+
+# Configure Better Auth
+BetterAuth.configure do |config|
+  config.secret_key = ENV['BETTER_AUTH_SECRET']
+  config.database_url = ENV['DATABASE_URL']
+end
+```
+
+### Rails Integration
+
+Add to your Gemfile:
+
+```ruby
+gem 'better_auth', require: 'better_auth/rails'
+```
+
+Then in your ApplicationController:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include BetterAuth::Rails::ControllerHelpers
+end
+```
+
+Now you have access to `current_user` and authentication methods:
+
+```ruby
+class PostsController < ApplicationController
+  before_action :authenticate_user!
+
+  def index
+    @posts = current_user.posts
+  end
+end
+```
+
+## Development
+
+### Quick Start
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/sebasxsala/better-auth.git
+cd better-auth/packages/better_auth
+
+# 2. Install dependencies
+make install
+# or: bundle install
+
+# 3. Run tests to verify everything works
+make ci
+```
+
+### Common Make Commands
+
+We use a **Makefile** to simplify commands. All have explanatory comments:
+
+```bash
+# View all available commands with description
+make help
+
+# Development
+make console          # Interactive console with gem loaded
+make lint            # Check code style
+make lint-fix        # Auto-fix style issues
+
+# Testing
+make test            # Run all tests
+make test-core       # Only core tests (Minitest)
+make test-coverage   # Tests with coverage
+make ci              # Full CI (lint + test)
+
+# Databases for testing
+make db-up           # Start PostgreSQL, MySQL, Redis
+make db-down         # Stop containers
+```
+
+### Branch Workflow
+
+This project uses a branch model similar to the upstream:
+
+**Main Branches:**
+
+- **`main`**: Stable code, ready for production
+- **`canary`**: Development/integration branch (like "development" but specific name)
+  - "Canary" comes from "canary in a coal mine" - where changes are tested before production
+  - Feature PRs go to `canary`
+  - When `canary` is stable, merge to `main` for release
+
+**Typical workflow:**
+
+```bash
+# 1. Create your feature branch from canary
+git checkout canary
+git pull origin canary
+git checkout -b feat/new-feature
+
+# 2. Make your changes and commits
+# ... code ...
+git add .
+git commit -m "feat(core): add support for X"
+
+# 3. Push and create PR towards canary
+git push origin feat/new-feature
+# Create PR on GitHub towards canary
+
+# 4. Once merged to canary and tested,
+#    merge canary → main for release
+```
+
+**Why canary instead of development?**
+
+- Common name in projects with frequent releases
+- Suggests it's an "experimental" version that might break
+- Allows multiple levels: feature → canary → main
+
+### How CI/CD Works
+
+**Pull Requests:**
+- Each PR runs: lint + tests on Ruby 3.2 and 3.3
+- Everything must pass before merging
+
+**Automatic Release (GitHub Actions):**
+
+Release is triggered on `push` to `main` when `lib/better_auth/version.rb` changes.
+
+```bash
+# STEP 1: Update version in lib/better_auth/version.rb
+# Example: VERSION = "0.1.1"
+
+# STEP 2: Commit and push to main
+git add lib/better_auth/version.rb
+git commit -m "chore: bump version to 0.1.1"
+git push origin main
+
+# STEP 3: GitHub Actions automatically:
+# - Runs tests
+# - Builds the gem
+# - Publishes to RubyGems (if version is new)
+# - Creates and pushes git tag (v0.1.1)
+# - Creates GitHub Release
+```
+
+**Required GitHub Configuration:**
+
+1. Go to Settings → Secrets and variables → Actions
+2. Add `RUBYGEMS_API_KEY` with your RubyGems API key
+3. The workflow `.github/workflows/release.yml` does the rest
+
+**Dry-run options:**
+
+```bash
+# Local packaging dry-run
+make release-check
+
+# CI dry-run from GitHub Actions
+# Actions -> Release -> Run workflow -> dry_run=true
+```
+
+### Manual Release (without GitHub Actions)
+
+Only if you need to do a manual release:
+
+```bash
+# 1. Update version.rb
+# 2. Build the gem
+gem build better_auth.gemspec
+
+# 3. Publish (you need to be logged into RubyGems)
+gem push better_auth-*.gem
+
+# 4. Create and push the tag
+git tag -a v0.1.1 -m "Release v0.1.1"
+git push origin --tags
+```
+
+### Project Structure
+
+```
+lib/
+  better_auth.rb              # Entry point
+  better_auth/
+    version.rb                # Gem version
+    core.rb                   # Core loader
+    core/                     # Core logic (framework-agnostic)
+
+test/                       # Core tests (Minitest)
+```
+
+**Conventions:**
+- Core: Framework-agnostic, uses Minitest
+- All code goes through StandardRB (Ruby style guide)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sebasxsala/better-auth. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/sebasxsala/better-auth/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Security
+
+If you discover a security vulnerability within Better Auth Ruby, please send an e-mail to [security@better-auth.com](mailto:security@better-auth.com).
+
+All reports will be promptly addressed, and you'll be credited accordingly.

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+desc "Run StandardRB linter"
+task :lint do
+  sh "bundle exec standardrb"
+end
+
+desc "Auto-fix StandardRB issues"
+task "lint:fix" do
+  sh "bundle exec standardrb --fix"
+end
+
+desc "Run full CI check (lint + test)"
+task ci: [:lint, :test]
+
+task default: :ci

data/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+### Reporting a Vulnerability
+
+If you believe you've found a security vulnerability, please follow these steps:
+
+1. Do not disclose the vulnerability publicly until it has been addressed by our
+   team.
+2. Email your findings to `security@better-auth.com` Include:
+   * A description of the vulnerability
+   * Steps to reproduce the vulnerability
+   * Potential impact of the vulnerability
+   * Any suggestions for mitigation
+   * Any other relevant information
+3. We will respond to your report within 72 hours.
+4. If the issue is confirmed, we will release a patch as soon as possible.
+
+### Disclosure Policy
+
+If the issue is confirmed, we will release a patch as soon as possible.
+Once a patch is released, we will disclose the issue publicly.
+If 90 days has elapsed and we still don't have a fix, we will disclose the issue
+publicly.
+
+## Supported Versions
+
+We only support the latest version of Better Auth Ruby.
+Older versions are not supported.

data/docker-compose.yml

@@ -0,0 +1,63 @@
+# Services for testing database adapters
+# These are used in CI for testing various database backends
+
+x-postgres-healthcheck: &postgres-healthcheck
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U user -d better_auth"]
+    interval: 1s
+    timeout: 5s
+    retries: 10
+
+x-mysql-healthcheck: &mysql-healthcheck
+  healthcheck:
+    test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uuser", "-ppassword"]
+    interval: 1s
+    timeout: 5s
+    retries: 10
+    start_period: 30s
+
+services:
+  redis:
+    image: redis:latest
+    container_name: redis
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 1s
+      timeout: 5s
+      retries: 10
+
+  postgres:
+    <<: *postgres-healthcheck
+    image: postgres:latest
+    container_name: postgres
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: better_auth
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql
+
+  mysql:
+    <<: *mysql-healthcheck
+    image: mysql:latest
+    container_name: mysql
+    environment:
+      MYSQL_ROOT_PASSWORD: root_password
+      MYSQL_DATABASE: better_auth
+      MYSQL_USER: user
+      MYSQL_PASSWORD: password
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+
+volumes:
+  redis_data:
+  postgres_data:
+  mysql_data:

data/lib/better_auth/core.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Core
+    # Core authentication logic goes here
+  end
+end

data/lib/better_auth/version.rb

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

data/lib/better_auth.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "better_auth/version"
+require_relative "better_auth/core"
+
+module BetterAuth
+  # Main entry point for Better Auth
+  # This module provides the core authentication functionality
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: better_auth
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Sebastian Sala
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: bcrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: standardrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Better Auth is a comprehensive, framework-agnostic authentication library
+  for Ruby. It provides a complete set of features out of the box with a plugin ecosystem.
+email:
+- sebastian.sala.tech@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- ".standard.yml"
+- ".vscode/settings.json"
+- AGENTS.md
+- CHANGELOG.md
+- CLAUDE.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE.md
+- Makefile
+- README.md
+- Rakefile
+- SECURITY.md
+- docker-compose.yml
+- lib/better_auth.rb
+- lib/better_auth/core.rb
+- lib/better_auth/version.rb
+homepage: https://github.com/sebasxsala/better-auth
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sebasxsala/better-auth
+  source_code_uri: https://github.com/sebasxsala/better-auth
+  changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Comprehensive authentication framework for Ruby/Rack
+test_files: []