rhales 0.4.0 → 0.5.3

data/Rakefile

@@ -0,0 +1,46 @@
+# Rakefile
+
+$:.unshift(File.expand_path('lib', __dir__))
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+# Load task files
+Dir.glob('lib/tasks/**/*.rake').each { |r| load r }
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+# Rhales specific tasks
+namespace :rhales do
+  desc 'Run Rhales tests only'
+  task :test do
+    system('bundle exec rspec spec/rhales/')
+  end
+
+  desc 'Generate Rhales documentation'
+  task :docs do
+    system('bundle exec yard doc lib/rhales/')
+  end
+
+  desc 'Validate Rhales templates in examples'
+  task :validate do
+    require 'rhales'
+
+    examples_dir = File.join(__dir__, 'examples', 'templates')
+    if Dir.exist?(examples_dir)
+      Dir.glob(File.join(examples_dir, '**', '*.rue')).each do |file|
+        puts "Validating #{file}..."
+        begin
+          Rhales::RueDocument.parse_file(file)
+          puts '  ✓ Valid'
+        rescue StandardError => ex
+          puts "  ✗ Error: #{ex.message}"
+        end
+      end
+    else
+      puts "No examples directory found at #{examples_dir}"
+    end
+  end
+end

data/debug_context.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require_relative 'lib/rhales'
+
+# Test props with both symbols and strings
+props = {
+  'greeting' => 'Hello World',
+  'user' => { 'name' => 'John Doe', 'role' => 'admin' },
+  'authenticated' => true,
+  'items' => [
+    { 'name' => 'Item 1', 'active' => true },
+    { 'name' => 'Item 2', 'active' => false }
+  ]
+}
+
+context = Rhales::Context.minimal(props: props)
+
+puts "=== Context Variables ==="
+puts "greeting: #{context.get('greeting')}"
+puts "user.name: #{context.get('user.name')}"
+puts "items.0.name: #{context.get('items.0.name')}"
+puts "items.0.active: #{context.get('items.0.active')}"
+puts "items.1.name: #{context.get('items.1.name')}"
+puts "items.1.active: #{context.get('items.1.active')}"
+puts "========================="

data/demo/rhales-roda-demo/.gitignore

@@ -0,0 +1,7 @@
+db/*.db
+.DS_Store
+*.log
+tmp/
+
+# Generated JSON Schemas (regenerate with: rake rhales:schema:generate)
+public/schemas/

data/demo/rhales-roda-demo/Gemfile

@@ -0,0 +1,32 @@
+source 'https://rubygems.org'
+
+# Web framework
+gem 'puma', '~> 6.4'
+gem 'rack-session', '~> 2.0'
+gem 'rackup'
+gem 'roda', '~> 3.84'
+
+# Authentication
+gem 'bcrypt', '~> 3.1'
+gem 'rodauth', '~> 2.36'
+gem 'rotp'
+gem 'rqrcode'
+
+# Database
+gem 'sequel', '~> 5.85'
+gem 'sqlite3', '~> 2.0'
+
+# Templates and utilities
+gem 'logger'
+gem 'mail'
+gem 'rake'
+gem 'rhales', path: '../..'  # Using local gem
+gem 'rspec'
+gem 'tilt'
+
+# Development
+group :development do
+  gem 'pry'
+  gem 'pry-byebug'
+  gem 'rerun'
+end

data/demo/rhales-roda-demo/Gemfile.lock

@@ -0,0 +1,151 @@
+PATH
+  remote: ../..
+  specs:
+    rhales (0.5.1)
+      json_schemer (~> 2.3)
+      logger
+      tilt (~> 2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    base64 (0.3.0)
+    bcrypt (3.1.20)
+    bigdecimal (3.2.2)
+    byebug (12.0.0)
+    chunky_png (1.4.0)
+    coderay (1.1.3)
+    date (3.4.1)
+    diff-lcs (1.6.2)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86-linux-musl)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    hana (1.3.7)
+    json_schemer (2.4.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    method_source (1.1.0)
+    mini_mime (1.1.5)
+    net-imap (0.5.9)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.11.0)
+      byebug (~> 12.0)
+      pry (>= 0.13, < 0.16)
+    puma (6.6.0)
+      nio4r (~> 2.0)
+    rack (3.1.16)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rackup (2.2.1)
+      rack (>= 3)
+    rake (13.3.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    regexp_parser (2.11.3)
+    rerun (0.14.0)
+      listen (~> 3.0)
+    roda (3.93.0)
+      rack
+    rodauth (2.39.0)
+      roda (>= 2.6.0)
+      sequel (>= 4)
+    rotp (6.3.0)
+    rqrcode (3.1.0)
+      chunky_png (~> 1.0)
+      rqrcode_core (~> 2.0)
+    rqrcode_core (2.0.0)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    sequel (5.94.0)
+      bigdecimal
+    simpleidn (0.2.3)
+    sqlite3 (2.7.1-aarch64-linux-gnu)
+    sqlite3 (2.7.1-aarch64-linux-musl)
+    sqlite3 (2.7.1-arm-linux-gnu)
+    sqlite3 (2.7.1-arm-linux-musl)
+    sqlite3 (2.7.1-arm64-darwin)
+    sqlite3 (2.7.1-x86-linux-gnu)
+    sqlite3 (2.7.1-x86-linux-musl)
+    sqlite3 (2.7.1-x86_64-darwin)
+    sqlite3 (2.7.1-x86_64-linux-gnu)
+    sqlite3 (2.7.1-x86_64-linux-musl)
+    tilt (2.3.0)
+    timeout (0.4.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  bcrypt (~> 3.1)
+  logger
+  mail
+  pry
+  pry-byebug
+  puma (~> 6.4)
+  rack-session (~> 2.0)
+  rackup
+  rake
+  rerun
+  rhales!
+  roda (~> 3.84)
+  rodauth (~> 2.36)
+  rotp
+  rqrcode
+  rspec
+  sequel (~> 5.85)
+  sqlite3 (~> 2.0)
+  tilt
+
+BUNDLED WITH
+   2.6.6

data/demo/rhales-roda-demo/MAIL.md

@@ -0,0 +1,405 @@
+# Mail Configuration in Rodauth
+
+This document explains how to configure SMTP and mail settings in Rodauth for sending authentication emails.
+
+## Overview
+
+Rodauth uses the **Mail gem** for email functionality. Email configuration happens at two levels:
+
+1. **Global Mail Configuration** - SMTP settings and delivery method
+2. **Rodauth Email Configuration** - Email addresses, subjects, and custom logic
+
+## Global Mail Configuration (SMTP Settings)
+
+Configure SMTP **before** loading Rodauth:
+
+```ruby
+require 'mail'
+
+# SMTP configuration
+Mail.defaults do
+  delivery_method :smtp, {
+    address:              'smtp.gmail.com',
+    port:                 587,
+    domain:               'yoursite.com',
+    user_name:            'your-email@gmail.com',
+    password:             'your-app-password',
+    authentication:       'plain',
+    enable_starttls_auto: true
+  }
+end
+
+# Then configure Rodauth
+plugin :rodauth do
+  enable :login, :reset_password, :verify_account
+  # ... other config
+end
+```
+
+## Rodauth Email Configuration
+
+Within your Rodauth configuration block:
+
+```ruby
+plugin :rodauth do
+  enable :reset_password, :verify_account
+
+  # Basic email settings
+  email_from 'noreply@yoursite.com'
+  email_subject_prefix '[YourSite] '
+
+  # Customize recipient (defaults to account email)
+  email_to do
+    account[:email] # or custom logic
+  end
+
+  # Override email sending for custom delivery
+  send_email do |email|
+    # Custom delivery logic
+    email.deliver!
+  end
+end
+```
+
+## Common SMTP Providers
+
+### Gmail
+
+```ruby
+Mail.defaults do
+  delivery_method :smtp, {
+    address:              'smtp.gmail.com',
+    port:                 587,
+    user_name:            'your-email@gmail.com',
+    password:             'your-app-password',  # Use app password, not account password
+    authentication:       'plain',
+    enable_starttls_auto: true
+  }
+end
+```
+
+**Note**: For Gmail, you need to use an App Password, not your regular Gmail password.
+
+### SendGrid
+
+```ruby
+Mail.defaults do
+  delivery_method :smtp, {
+    address:        'smtp.sendgrid.net',
+    port:           587,
+    user_name:      'apikey',
+    password:       'your-sendgrid-api-key',
+    authentication: 'plain',
+    enable_starttls_auto: true
+  }
+end
+```
+
+### Mailgun
+
+```ruby
+Mail.defaults do
+  delivery_method :smtp, {
+    address:        'smtp.mailgun.org',
+    port:           587,
+    user_name:      'postmaster@your-domain.mailgun.org',
+    password:       'your-mailgun-password',
+    authentication: 'plain',
+    enable_starttls_auto: true
+  }
+end
+```
+
+### Amazon SES
+
+```ruby
+Mail.defaults do
+  delivery_method :smtp, {
+    address:        'email-smtp.us-east-1.amazonaws.com',
+    port:           587,
+    user_name:      'your-ses-smtp-username',
+    password:       'your-ses-smtp-password',
+    authentication: 'plain',
+    enable_starttls_auto: true
+  }
+end
+```
+
+## Environment-Based Configuration
+
+Configure different delivery methods per environment:
+
+```ruby
+case ENV['RACK_ENV']
+when 'production'
+  Mail.defaults do
+    delivery_method :smtp, {
+      address:   ENV['SMTP_ADDRESS'],
+      port:      ENV['SMTP_PORT'],
+      user_name: ENV['SMTP_USERNAME'],
+      password:  ENV['SMTP_PASSWORD'],
+      authentication: 'plain',
+      enable_starttls_auto: true
+    }
+  end
+when 'development'
+  Mail.defaults do
+    delivery_method :file, location: 'tmp/mails'
+  end
+when 'test'
+  Mail.defaults do
+    delivery_method :test
+  end
+end
+```
+
+## Custom Email Templates
+
+Override email content by defining methods in your Rodauth configuration:
+
+### Custom Reset Password Email
+
+```ruby
+plugin :rodauth do
+  enable :reset_password
+
+  # Custom email subject
+  reset_password_email_subject do
+    "Reset your #{domain} password"
+  end
+
+  # Custom email body
+  reset_password_email_body do
+    <<~EMAIL
+      Hello,
+
+      Someone has requested a password reset for your account.
+
+      Click here to reset: #{reset_password_email_link}
+
+      If you didn't request this, please ignore this email.
+
+      Thanks,
+      The #{domain} Team
+    EMAIL
+  end
+end
+```
+
+### Custom Verification Email
+
+```ruby
+plugin :rodauth do
+  enable :verify_account
+
+  verify_account_email_subject do
+    "Please verify your #{domain} account"
+  end
+
+  verify_account_email_body do
+    <<~EMAIL
+      Welcome to #{domain}!
+
+      Please verify your account by clicking this link:
+      #{verify_account_email_link}
+
+      Thanks for signing up!
+    EMAIL
+  end
+end
+```
+
+## Email Configuration Methods
+
+Key configuration methods available in Rodauth:
+
+```ruby
+plugin :rodauth do
+  # Sender email address (defaults to "webmaster@#{domain}")
+  email_from 'noreply@yoursite.com'
+
+  # Subject prefix for all emails
+  email_subject_prefix '[YourSite] '
+
+  # Customize recipient email address
+  email_to do
+    account[:email] # or custom logic
+  end
+
+  # Custom email creation
+  create_email do |subject, body|
+    mail = Mail.new
+    mail.from = email_from
+    mail.to = email_to
+    mail.subject = "#{email_subject_prefix}#{subject}"
+    mail.body = body
+    # Add custom headers, attachments, etc.
+    mail
+  end
+
+  # Custom email sending
+  send_email do |email|
+    # Add logging, error handling, etc.
+    puts "Sending email to #{email.to}: #{email.subject}"
+    email.deliver!
+  end
+end
+```
+
+## Alternative Delivery Methods
+
+### File Delivery (Development)
+
+Saves emails to files instead of sending them:
+
+```ruby
+Mail.defaults do
+  delivery_method :file, location: 'tmp/mails'
+end
+```
+
+### Test Delivery
+
+Captures emails in memory for testing:
+
+```ruby
+Mail.defaults do
+  delivery_method :test
+end
+
+# Access sent emails in tests
+Mail::TestMailer.deliveries.last
+```
+
+### Sendmail
+
+Use local sendmail binary:
+
+```ruby
+Mail.defaults do
+  delivery_method :sendmail
+end
+```
+
+## Email Features
+
+Features that send emails and can be customized:
+
+- **reset_password** - Password reset emails
+- **verify_account** - Account verification emails
+- **verify_login_change** - Login change verification emails
+- **change_password_notify** - Password change notifications
+- **lockout** - Account lockout notifications
+- **email_auth** - Passwordless email authentication
+- **otp_lockout_email** - OTP lockout notifications
+- **otp_modify_email** - OTP setup/disable notifications
+- **webauthn_modify_email** - WebAuthn setup/removal notifications
+
+## Security Considerations
+
+### HMAC Protection
+
+Enable HMAC protection for email tokens:
+
+```ruby
+plugin :rodauth do
+  # Set an HMAC secret for token security
+  hmac_secret 'your-secret-key-here'
+
+  # Disable raw token acceptance (recommended for production)
+  allow_raw_email_token? false
+end
+```
+
+### Rate Limiting
+
+Built-in rate limiting prevents email spam:
+
+```ruby
+plugin :rodauth do
+  enable :reset_password
+
+  # Don't resend reset email within 5 minutes
+  reset_password_skip_resend_email_within 300
+end
+```
+
+## Testing Email
+
+In your test suite:
+
+```ruby
+# Configure test delivery
+Mail.defaults do
+  delivery_method :test
+end
+
+# In tests, check sent emails
+def test_password_reset_email
+  post '/reset-password', email: 'user@example.com'
+
+  email = Mail::TestMailer.deliveries.last
+  assert_includes email.to, 'user@example.com'
+  assert_includes email.subject, 'Reset Password'
+  assert_includes email.body.to_s, 'reset'
+end
+
+# Clear deliveries between tests
+def setup
+  Mail::TestMailer.deliveries.clear
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication failures**: Ensure you're using the correct credentials and authentication method
+2. **Port blocked**: Try different ports (25, 465, 587, 2525)
+3. **Gmail App Passwords**: Regular Gmail passwords won't work with SMTP
+4. **Development emails not visible**: Check your delivery method and file location
+
+### Debug Logging
+
+Enable Mail gem logging:
+
+```ruby
+Mail.defaults do
+  delivery_method :smtp, {
+    # ... SMTP settings
+    openssl_verify_mode: 'none',
+    enable_starttls_auto: true
+  }
+end
+
+# Enable logging
+Mail.defaults do
+  retriever_method :imap, {
+    # ... settings
+  }
+end
+```
+
+### Testing SMTP Configuration
+
+Test your SMTP settings independently:
+
+```ruby
+require 'mail'
+
+Mail.defaults do
+  delivery_method :smtp, {
+    # your SMTP settings
+  }
+end
+
+mail = Mail.new do
+  from     'test@yoursite.com'
+  to       'recipient@example.com'
+  subject  'Test email'
+  body     'This is a test email'
+end
+
+mail.deliver!
+puts "Email sent successfully!"
+```