rodauth-tools 0.3.0

data/CLAUDE.md

@@ -0,0 +1,262 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Purpose
+
+Framework-agnostic utilities for Rodauth authentication:
+
+1. **External Rodauth Features** - `table_guard` for database validation, `external_identity` for external service IDs, `hmac_secret_guard` for HMAC secret validation, `jwt_secret_guard` for JWT secret validation
+2. **Sequel Migration Generator** - Generate migrations for 19 Rodauth features
+
+**Not a framework adapter.** For Rails integration, use rodauth-rails. This project demonstrates Rodauth's extensibility and provides reference implementations.
+
+**Status:** Experimental learning project. Not published to RubyGems.
+
+**Recent Refactoring (2025-10):** Namespace changed from `Rodauth::Rack::Generators::Migration` to `Rodauth::Tools::Migration`. This reflects the project's evolution away from being a Rack adapter toward being a collection of framework-agnostic utilities. The migration generator is now deprecated in favor of the `table_guard` feature with `sequel_mode`.
+
+## Development Commands
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Interactive console with helpers
+bin/console
+```
+
+## Architecture Overview
+
+### Core Components
+
+**lib/rodauth/features/table_guard.rb** - External Rodauth feature
+
+- Uses `Rodauth::Feature.define(:table_guard, :TableGuard)` pattern
+- Validates database tables exist for enabled features at `post_configure` time
+- Provides introspection methods: `missing_tables`, `table_status`, `list_all_required_tables`
+- Configurable modes: `:warn`, `:error`, `:silent`, or custom block handler
+- Demonstrates proper feature lifecycle hooks and configuration DSL
+
+**lib/rodauth/features/hmac_secret_guard.rb** - External Rodauth feature
+
+- Uses `Rodauth::Feature.define(:hmac_secret_guard, :HmacSecretGuard)` pattern
+- Automatically loads HMAC secret from environment variable (defaults to `HMAC_SECRET`)
+- Validates secret is configured at application startup via `post_configure` hook
+- Production mode: Raises `ConfigurationError` if secret missing
+- Development mode: Logs warning and uses configurable fallback secret
+- Deletes secret from ENV after loading for security
+- Provides `production?` and `validate_secrets!` public methods
+
+**lib/rodauth/features/jwt_secret_guard.rb** - External Rodauth feature
+
+- Uses `Rodauth::Feature.define(:jwt_secret_guard, :JwtSecretGuard)` pattern
+- Automatically loads JWT secret from environment variable (defaults to `JWT_SECRET`)
+- Validates secret is configured at application startup via `post_configure` hook
+- Production mode: Raises `ConfigurationError` if secret missing
+- Development mode: Logs warning and uses configurable fallback secret
+- Deletes secret from ENV after loading for security
+- Provides `production?` and `validate_secrets!` public methods
+- Defines `jwt_secret` configuration method for standalone use
+
+**lib/rodauth/tools/migration.rb** - Sequel migration generator
+
+- Generates database migrations for 19 Rodauth features
+- Uses ERB templates in `lib/rodauth/tools/migration/sequel/`
+- Provides `generate()` for migration content and `migration_name()` for filename
+- Uses dry-inflector gem for robust table name pluralization
+- Mock database adapter pattern when no real DB connection provided
+- Deprecated in favor of table_guard feature with sequel_mode
+
+### How Rodauth Features Work
+
+Rodauth features are modules that mix into `Rodauth::Auth` instances:
+
+```ruby
+Feature.define(:feature_name, :FeatureName) do
+  # Configuration methods (overridable by users)
+  auth_value_method :setting_name, 'default_value'
+
+  # Public methods (overridable by users)
+  auth_methods :public_method
+
+  # Private methods (not overridable)
+  auth_private_methods :internal_helper
+
+  # Lifecycle hook - runs after configuration
+  def post_configure
+    super if defined?(super)
+    # Initialization code
+  end
+end
+```
+
+**Key Pattern:** Methods defined in features become part of the Rodauth instance. Users override them in configuration blocks:
+
+```ruby
+plugin :rodauth do
+  enable :feature_name
+
+  setting_name 'custom_value'  # Override auth_value_method
+
+  public_method do             # Override auth_methods
+    # Custom implementation
+  end
+end
+```
+
+### Table Guard Implementation Details
+
+**Logger Suppression:** The `table_exists?` method temporarily suppresses Sequel's logger during table existence checks. This prevents confusing ERROR logs from Sequel when checking non-existent tables (Sequel's `table_exists?` attempts a SELECT and logs the exception before catching it).
+
+**Configuration Storage:** Uses instance variables set by `auth_value_method`:
+
+- Block configs stored as Procs in `@table_guard_mode`
+- Symbol configs stored directly as `:warn`, `:error`, `:silent`
+
+**Check Strategy:**
+
+1. `should_check_tables?` examines `@table_guard_mode` to decide if checking is needed
+2. Returns `true` if mode is a Proc (block), enabling custom handlers
+3. Returns `true` if mode is `:warn` or `:error`, `false` for `:silent`
+
+**Execution Flow:**
+
+1. `post_configure` hook calls `check_required_tables!` if `should_check_tables?` returns true
+2. `check_required_tables!` gets missing tables via `missing_tables`
+3. For symbol modes (`:warn`, `:error`), handles directly
+4. For block modes, calls block with missing tables, handles return value (`:error`, `:continue`, String)
+
+**Introspection Methods:**
+
+- `all_table_methods` - Finds all methods ending in `_table` using Ruby reflection
+- `missing_tables` - Checks each table method against `db.table_exists?`
+- `table_status` - Returns array of hashes with method, table name, and existence status
+
+### Migration Generator Architecture
+
+**Note:** The Migration class is deprecated. For new code, use the `table_guard` feature with `sequel_mode` instead.
+
+**Template System:**
+
+- Each feature has ERB template in `lib/rodauth/tools/migration/sequel/`
+- Templates use binding from Migration instance for variables like `table_prefix`
+- `generate()` loads, evaluates, and concatenates all feature templates
+
+**Pluralization:**
+
+- Uses `dry-inflector` gem for intelligent pluralization (e.g., "status" → "statuses")
+- Helper method `pluralize(str)` available in templates via ERB binding
+- Removed Rails/ActiveRecord dependencies (68 lines of cruft eliminated)
+
+**Database Adapter Pattern:**
+
+- `MockSequelDatabase` simulates database when no real connection provided
+- Allows template generation without active database
+- Real `Sequel::Database` object can be passed for actual migrations
+- Supports PostgreSQL, MySQL, and SQLite database types
+
+### Hidden Tables Architecture
+
+**Problem:** Some tables are created in ERB templates without corresponding `*_table` methods in Rodauth features.
+
+**Example from base.erb:**
+
+```ruby
+# base.erb creates THREE tables:
+create_table(:account_statuses)        # NO METHOD - Hidden!
+create_table(:account_password_hashes) # NO METHOD - Hidden!
+create_table(:accounts)                # Has accounts_table method ✓
+```
+
+**Why This Happens:**
+
+- `account_statuses` - Lookup table for status values (Unverified=1, Verified=2, Closed=3). No method because users configure status IDs directly via `account_open_status_value`, etc.
+- `account_password_hashes` - Separate table for security. Method is `account_password_hash_table` (singular), but ERB uses pluralized form based on `table_prefix`.
+
+#### Solution: TemplateInspector Module
+
+`lib/rodauth/template_inspector.rb` extracts table names directly from ERB templates by:
+
+1. Creating minimal binding context with `table_prefix`, `pluralize`, and mock `db`
+2. Evaluating ERB templates to render actual Ruby code
+3. Parsing rendered code for `create_table()` calls using regex
+4. Returning complete list of tables, including hidden ones
+
+**Usage:**
+
+```ruby
+# Extract all tables for a feature
+tables = TemplateInspector.extract_tables_from_template(
+  :base,
+  table_prefix: 'account'
+)
+# => [:account_statuses, :account_password_hashes, :accounts]
+
+# Get tables for multiple features
+all_tables = TemplateInspector.all_tables_for_features(
+  [:base, :verify_account, :lockout],
+  table_prefix: 'account'
+)
+```
+
+**Impact on DROP Operations:**
+
+Before TemplateInspector, `generate_drop_statements` only dropped dynamically discovered tables, missing hidden ones. Now it extracts the complete table list from ERB templates, ensuring all tables are properly dropped in correct dependency order.
+
+**Key Insight:** ERB templates are the single source of truth for table schemas. By extracting information FROM templates instead of duplicating it in Ruby constants, we maintain consistency and eliminate hardcoded mappings.
+
+## Testing Patterns
+
+**RSpec Structure:**
+
+- `spec/spec_helper.rb` - Minimal configuration, loads `rodauth/rack`
+- Feature specs test both behavior and configuration
+- Migration generator specs verify template output and configuration
+
+**Console Helpers:**
+
+- `setup_test_db` - Creates in-memory SQLite database with tables
+- `create_app(db, features: [...])` - Creates Roda app with Rodauth configured
+- Useful for interactive testing of table_guard and migration generator
+
+## Documentation Reference
+
+**docs/rodauth-features-api.md** - Complete reference for feature development DSL methods
+
+**docs/rodauth-internals.rdoc** - Object model explanation:
+
+- `Rodauth::Auth` - Authentication class (where features mix in)
+- `Rodauth::Configuration` - Configuration DSL class
+- `Rodauth::Feature` - Module subclass for feature definitions
+- `Rodauth::FeatureConfiguration` - Configuration module for features
+
+**docs/rodauth-mail.md** - Email/SMTP configuration patterns
+
+**DEVELOPMENT.md** - Architectural decisions, standard Rack integration pattern
+
+## Integration Pattern
+
+Rodauth integrates with any Rack app via Roda middleware (NOT via this library):
+
+```ruby
+# Create Roda app with Rodauth
+class RodauthApp < Roda
+  plugin :middleware
+  plugin :rodauth do
+    enable :login, :logout
+    enable :table_guard  # ← Feature from this library
+    db DB
+  end
+
+  route do |r|
+    r.rodauth
+    env['rodauth'] = rodauth
+  end
+end
+
+# Mount as Rack middleware
+use RodauthApp
+run MyApp
+```
+
+Access in your app: `request.env['rodauth']` provides all authentication methods.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public 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.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to rodauth-tools
+
+Thank you for your interest in contributing to rodauth-tools!
+
+## Development Setup
+
+1. Fork and clone the repository:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/rodauth-tools.git
+   cd rodauth-tools
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   bundle install
+   ```
+
+3. Install pre-commit hooks:
+
+   ```bash
+   # Install pre-commit (if not already installed)
+   pip install pre-commit
+   # or
+   brew install pre-commit
+
+   # Install the git hook scripts
+   pre-commit install
+   pre-commit install --hook-type commit-msg
+   ```
+
+4. Run tests:
+
+   ```bash
+   bundle exec rspec
+   ```
+
+## Pre-commit Hooks
+
+This project uses pre-commit to ensure code quality. The hooks will run automatically on `git commit`.
+
+To manually run all hooks on all files:
+
+```bash
+pre-commit run --all-files
+```
+
+To skip hooks (not recommended):
+
+```bash
+git commit --no-verify
+```
+
+### Configured Hooks
+
+- **File checks**: Trailing whitespace, end-of-file, large files, merge conflicts
+- **RuboCop**: Ruby style and linting (auto-corrects when possible)
+- **Bundler Audit**: Security vulnerability checks
+- **Markdown linting**: Ensures consistent Markdown formatting
+- **Commit message**: Enforces conventional commit format
+
+## Code Style
+
+We use RuboCop for Ruby code style. Configuration is in `.rubocop.yml`.
+
+Key conventions:
+
+- Ruby 3.2+ syntax
+- Double quotes for strings
+- 2-space indentation
+
+## Commit Messages
+
+Follow conventional commits format:
+
+```text
+type(scope): subject
+
+body (optional)
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+Examples:
+
+- `feat: add CSRF protection to base adapter`
+- `fix: correct session reset behavior in Rails adapter`
+- `docs: update installation instructions`
+
+## Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+```
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Make your changes with clear, conventional commits
+3. Ensure all tests pass and pre-commit hooks succeed
+4. Update documentation as needed
+5. Submit a pull request with a clear description of changes
+
+## Questions?
+
+Feel free to open an issue for discussion before starting major work.

data/Gemfile

@@ -0,0 +1,35 @@
+# Gemfile
+#
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'dry-inflector'
+gem 'irb'
+gem 'rake', '~> 13.3'
+
+group :development do
+  gem 'bundler-audit'
+  gem 'rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.81'
+  gem 'rubocop-rake'
+  gem 'rubocop-rspec'
+end
+
+group :test do
+  gem 'bcrypt', '~> 3.1'
+  gem 'capybara'
+  gem 'jwt', '~> 3.1'
+  gem 'rack-test', '~> 2.1'
+  gem 'rails', '>= 6.0'
+  gem 'rotp'
+  gem 'rqrcode'
+  gem 'sequel-activerecord_connection', '~> 2.0'
+  gem 'sqlite3', '~> 2.8'
+  gem 'tilt', '~> 2.4'
+  gem 'tryouts', '~> 3.0'
+  gem 'warning'
+  gem 'webauthn' unless RUBY_ENGINE == 'jruby'
+end