otto 1.2.0 → 1.4.0

data/examples/helpers_demo/app.rb

@@ -0,0 +1,244 @@
+require 'otto'
+require 'json'
+
+class HelpersDemo
+  def initialize(req, res)
+    @req, @res = req, res
+  end
+
+  attr_reader :req, :res
+
+  def index
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Otto Request & Response Helpers Demo</h1>
+      <p>This demo shows Otto's built-in request and response helpers.</p>
+
+      <h2>Available Demos:</h2>
+      <ul>
+        <li><a href="/request-info">Request Information</a> - Shows client IP, user agent, security info</li>
+        <li><a href="/locale-demo?locale=es">Locale Detection</a> - Demonstrates locale detection and configuration</li>
+        <li><a href="/secure-cookie">Secure Cookies</a> - Sets secure cookies with proper options</li>
+        <li><a href="/headers">Response Headers</a> - Shows security headers and custom headers</li>
+        <li>
+          <form method="POST" action="/csp-demo">
+            <button type="submit">CSP Headers Demo</button> - Content Security Policy with nonce
+          </form>
+        </li>
+      </ul>
+
+      <h2>Try These URLs:</h2>
+      <ul>
+        <li><a href="/locale-demo?locale=fr">French locale</a></li>
+        <li><a href="/locale-demo?locale=invalid">Invalid locale (falls back to default)</a></li>
+      </ul>
+    HTML
+  end
+
+  def request_info
+    # Demonstrate request helpers
+    info = {
+      'Client IP' => req.client_ipaddress,
+      'User Agent' => req.user_agent,
+      'HTTP Host' => req.http_host,
+      'Server Name' => req.current_server_name,
+      'Request Path' => req.request_path,
+      'Request URI' => req.request_uri,
+      'Is Local?' => req.local?,
+      'Is Secure?' => req.secure?,
+      'Is AJAX?' => req.ajax?,
+      'Current Absolute URI' => req.current_absolute_uri,
+      'Request Method' => req.request_method
+    }
+
+    # Show collected proxy headers
+    proxy_headers = req.collect_proxy_headers(
+      header_prefix: 'X_DEMO_',
+      additional_keys: ['HTTP_ACCEPT', 'HTTP_ACCEPT_LANGUAGE']
+    )
+
+    # Format request details for logging
+    request_details = req.format_request_details(header_prefix: 'X_DEMO_')
+
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Request Information</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Basic Request Info:</h2>
+      <table border="1" style="border-collapse: collapse;">
+        #{info.map { |k, v| "<tr><td><strong>#{k}</strong></td><td>#{v}</td></tr>" }.join("\n        ")}
+      </table>
+
+      <h2>Proxy Headers:</h2>
+      <pre>#{proxy_headers}</pre>
+
+      <h2>Formatted Request Details (for logging):</h2>
+      <pre>#{request_details}</pre>
+
+      <h2>Application Path Helper:</h2>
+      <p>App path for ['api', 'v1', 'users']: <code>#{req.app_path('api', 'v1', 'users')}</code></p>
+    HTML
+  end
+
+  def locale_demo
+    # Demonstrate locale detection with Otto configuration
+    current_locale = req.check_locale!(req.params['locale'], {
+      preferred_locale: 'es', # Simulate user preference
+      locale_env_key: 'demo.locale',
+      debug: true
+    })
+
+    # Show what was stored in environment
+    stored_locale = req.env['demo.locale']
+
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Locale Detection Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Locale Detection Results:</h2>
+      <table border="1" style="border-collapse: collapse;">
+        <tr><td><strong>Detected Locale</strong></td><td>#{current_locale}</td></tr>
+        <tr><td><strong>Stored in Environment</strong></td><td>#{stored_locale}</td></tr>
+        <tr><td><strong>Query Parameter</strong></td><td>#{req.params['locale'] || 'none'}</td></tr>
+        <tr><td><strong>Accept-Language Header</strong></td><td>#{req.env['HTTP_ACCEPT_LANGUAGE'] || 'none'}</td></tr>
+      </table>
+
+      <h2>Locale Sources (in precedence order):</h2>
+      <ol>
+        <li>URL Parameter: <code>?locale=#{req.params['locale'] || 'none'}</code></li>
+        <li>User Preference: <code>es</code> (simulated)</li>
+        <li>Rack Locale: <code>#{req.env['rack.locale']&.first || 'none'}</code></li>
+        <li>Default: <code>en</code></li>
+      </ol>
+
+      <h2>Try Different Locales:</h2>
+      <ul>
+        <li><a href="/locale-demo?locale=en">English (en)</a></li>
+        <li><a href="/locale-demo?locale=es">Spanish (es)</a></li>
+        <li><a href="/locale-demo?locale=fr">French (fr)</a></li>
+        <li><a href="/locale-demo?locale=invalid">Invalid locale</a></li>
+        <li><a href="/locale-demo">No locale parameter</a></li>
+      </ul>
+    HTML
+  end
+
+  def secure_cookie
+    # Demonstrate secure cookie helpers
+    res.send_secure_cookie('demo_secure', 'secure_value_123', 3600, {
+      path: '/helpers_demo',
+      secure: !req.local?, # Only secure in production
+      same_site: :strict
+    })
+
+    res.send_session_cookie('demo_session', 'session_value_456', {
+      path: '/helpers_demo'
+    })
+
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Secure Cookies Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Cookies Set:</h2>
+      <ul>
+        <li><strong>demo_secure</strong> - Secure cookie with 1 hour TTL</li>
+        <li><strong>demo_session</strong> - Session cookie (no expiration)</li>
+      </ul>
+
+      <h2>Cookie Security Features:</h2>
+      <ul>
+        <li>Secure flag (HTTPS only in production)</li>
+        <li>HttpOnly flag (prevents XSS access)</li>
+        <li>SameSite=Strict (CSRF protection)</li>
+        <li>Proper expiration handling</li>
+      </ul>
+
+      <p>Check your browser's developer tools to see the cookie headers!</p>
+    HTML
+  end
+
+  def csp_demo
+    # Demonstrate CSP headers with nonce
+    nonce = SecureRandom.base64(16)
+
+    res.send_csp_headers('text/html; charset=utf-8', nonce, {
+      development_mode: req.local?,
+      debug: true
+    })
+
+    res.body = <<~HTML
+      <h1>Content Security Policy Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>CSP Header Generated</h2>
+      <p>This page includes a CSP header with a nonce. Check the response headers!</p>
+
+      <h2>Nonce Value:</h2>
+      <p><code>#{nonce}</code></p>
+
+      <h2>Inline Script with Nonce:</h2>
+      <script nonce="#{nonce}">
+        console.log('This script runs because it has the correct nonce!');
+        document.addEventListener('DOMContentLoaded', function() {
+          document.getElementById('nonce-demo').innerHTML = 'Nonce verification successful!';
+        });
+      </script>
+
+      <div id="nonce-demo" style="padding: 10px; background: #d4edda; border: 1px solid #c3e6cb; color: #155724;">
+        Loading...
+      </div>
+
+      <p><strong>Note:</strong> Without the nonce, inline scripts would be blocked by CSP.</p>
+    HTML
+  end
+
+  def show_headers
+    # Demonstrate response headers and security features
+    res.set_cookie('demo_header', {
+      value: 'header_demo_value',
+      max_age: 1800,
+      secure: !req.local?,
+      httponly: true
+    })
+
+    # Add cache control
+    res.no_cache!
+
+    # Get security headers that would be added
+    security_headers = res.cookie_security_headers
+
+    res.headers['content-type'] = 'text/html'
+    res.headers['X-Demo-Header'] = 'Custom header value'
+
+    res.body = <<~HTML
+      <h1>Response Headers Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Custom Headers Set:</h2>
+      <ul>
+        <li><strong>X-Demo-Header:</strong> Custom header value</li>
+        <li><strong>Cache-Control:</strong> no-store, no-cache, must-revalidate, max-age=0</li>
+        <li><strong>Set-Cookie:</strong> demo_header (with security options)</li>
+      </ul>
+
+      <h2>Security Headers Available:</h2>
+      <table border="1" style="border-collapse: collapse;">
+        #{security_headers.map { |k, v| "<tr><td><strong>#{k}</strong></td><td>#{v}</td></tr>" }.join("\n        ")}
+      </table>
+
+      <p>Use your browser's developer tools to inspect all response headers!</p>
+    HTML
+  end
+
+  def not_found
+    res.status = 404
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>404 - Page Not Found</h1>
+      <p><a href="/">← Back to index</a></p>
+      <p>This is a custom 404 page demonstrating error handling.</p>
+    HTML
+  end
+end

data/examples/helpers_demo/config.ru

@@ -0,0 +1,26 @@
+require_relative '../../lib/otto'
+require_relative 'app'
+
+# Global configuration for all Otto instances
+Otto.configure do |opts|
+  opts.available_locales = {
+    'en' => 'English',
+    'es' => 'Spanish',
+    'fr' => 'French'
+  }
+  opts.default_locale = 'en'
+end
+
+# Configure Otto with security features
+app = Otto.new("./routes", {
+  # Security features
+  csrf_protection: true,
+  request_validation: true,
+  trusted_proxies: ['127.0.0.1', '::1']
+})
+
+# Enable additional security headers
+app.enable_csp_with_nonce!(debug: true)
+app.enable_frame_protection!('SAMEORIGIN')
+
+run app

data/examples/helpers_demo/routes

@@ -0,0 +1,7 @@
+GET   /                         HelpersDemo#index
+GET   /request-info             HelpersDemo#request_info
+GET   /locale-demo              HelpersDemo#locale_demo
+GET   /secure-cookie            HelpersDemo#secure_cookie
+POST  /csp-demo                 HelpersDemo#csp_demo
+GET   /headers                  HelpersDemo#show_headers
+GET   /404                      HelpersDemo#not_found

data/examples/security_features/app.rb

@@ -9,8 +9,8 @@ class SecureApp
   attr_reader :req, :res
 
   def initialize(req, res)
-    @req = req
-    @res = res
+    @req                        = req
+    @res                        = res
     res.headers['content-type'] = 'text/html; charset=utf-8'
   end
 
@@ -28,49 +28,47 @@ class SecureApp
         <p class="otto-mb-md">Security demonstration for the Otto framework</p>
       </div>
 
-      #{otto_card("CSRF Protected Feedback") do
-
+      #{otto_card('CSRF Protected Feedback') do
         <<~FORM
           <form method="post" action="/feedback" class="otto-form">
             #{csrf_tag}
             <label>Message:</label>
-            #{otto_textarea("message", placeholder: "Enter your feedback...", required: true)}
-            #{otto_button("Submit Feedback", variant: "primary")}
+            #{otto_textarea('message', placeholder: 'Enter your feedback...', required: true)}
+            #{otto_button('Submit Feedback', variant: 'primary')}
           </form>
         FORM
-
       end}
 
-      #{otto_card("File Upload Validation") do
+      #{otto_card('File Upload Validation') do
         <<~UPLOAD
           <form method="post" action="/upload" enctype="multipart/form-data" class="otto-form">
             #{csrf_tag}
             <label>Choose file:</label>
             <input type="file" name="upload_file" class="otto-input">
-            #{otto_button("Upload File", variant: "primary")}
+            #{otto_button('Upload File', variant: 'primary')}
           </form>
         UPLOAD
       end}
 
-      #{otto_card("User Profile Input Validation") do
+      #{otto_card('User Profile Input Validation') do
         <<~PROFILE
           <form method="post" action="/profile" class="otto-form">
             #{csrf_tag}
             <label>Name:</label>
-            #{otto_input("name", placeholder: "Your name", required: true)}
+            #{otto_input('name', placeholder: 'Your name', required: true)}
 
             <label>Email:</label>
-            #{otto_input("email", type: "email", placeholder: "your@email.com", required: true)}
+            #{otto_input('email', type: 'email', placeholder: 'your@email.com', required: true)}
 
             <label>Bio:</label>
-            #{otto_textarea("bio", placeholder: "Tell us about yourself...")}
+            #{otto_textarea('bio', placeholder: 'Tell us about yourself...')}
 
-            #{otto_button("Update Profile", variant: "primary")}
+            #{otto_button('Update Profile', variant: 'primary')}
           </form>
         PROFILE
       end}
 
-      #{otto_card("Security Information") do
+      #{otto_card('Security Information') do
         <<~INFO
           <h3>Security Features Active:</h3>
           <ul>
@@ -87,13 +85,13 @@ class SecureApp
           </p>
 
           <p class="otto-mt-md">
-            #{otto_link("View Request Headers", "/headers")}
+            #{otto_link('View Request Headers', '/headers')}
           </p>
         INFO
       end}
     HTML
 
-    res.body = otto_page(content, "Otto Security Features")
+    res.body = otto_page(content, 'Otto Security Features')
   end
 
   def receive_feedback
@@ -104,29 +102,28 @@ class SecureApp
         safe_message = validate_input(message, max_length: 1000, allow_html: false)
       else
         safe_message = message.to_s.strip
-        raise "Message too long" if safe_message.length > 1000
+        raise 'Message too long' if safe_message.length > 1000
       end
 
-      if safe_message.empty?
-        content = otto_alert("error", "Validation Error", "Message cannot be empty.")
+      content = if safe_message.empty?
+        otto_alert('error', 'Validation Error', 'Message cannot be empty.')
       else
-        content = <<~HTML
-          #{otto_alert("success", "Feedback Received", "Thank you for your feedback!")}
+        <<~HTML
+          #{otto_alert('success', 'Feedback Received', 'Thank you for your feedback!')}
 
-          #{otto_card("Your Message") do
+          #{otto_card('Your Message') do
             otto_code_block(safe_message, 'text')
           end}
         HTML
-      end
-
-    rescue Otto::Security::ValidationError => e
-      content = otto_alert("error", "Security Validation Failed", e.message)
-    rescue => e
-      content = otto_alert("error", "Processing Error", "An error occurred processing your request.")
+                end
+    rescue Otto::Security::ValidationError => ex
+      content = otto_alert('error', 'Security Validation Failed', ex.message)
+    rescue StandardError
+      content = otto_alert('error', 'Processing Error', 'An error occurred processing your request.')
     end
 
-    content += "<p class=\"otto-mt-lg\">#{otto_link("← Back to form", "/")}</p>"
-    res.body = otto_page(content, "Feedback Response")
+    content += "<p class=\"otto-mt-lg\">#{otto_link('← Back to form', '/')}</p>"
+    res.body = otto_page(content, 'Feedback Response')
   end
 
   def upload_file
@@ -134,31 +131,39 @@ class SecureApp
       uploaded_file = req.params['upload_file']
 
       if uploaded_file.nil? || uploaded_file.empty?
-        content = otto_alert("error", "Upload Error", "No file was selected.")
+        content = otto_alert('error', 'Upload Error', 'No file was selected.')
       else
-        filename = uploaded_file[:filename] rescue uploaded_file.original_filename rescue 'unknown'
+        begin
+          filename = begin
+                     uploaded_file[:filename]
+          rescue StandardError
+                     uploaded_file.original_filename
+          end
+        rescue StandardError
+          'unknown'
+        end
 
-        if respond_to?(:sanitize_filename)
-          safe_filename = sanitize_filename(filename)
+        safe_filename = if respond_to?(:sanitize_filename)
+          sanitize_filename(filename)
         else
-          safe_filename = File.basename(filename.to_s).gsub(/[^\w\-_\.]/, '_')
-        end
+          File.basename(filename.to_s).gsub(/[^\w\-_\.]/, '_')
+                        end
 
         file_info = {
-          "Original filename" => filename,
-          "Sanitized filename" => safe_filename,
-          "Content type" => uploaded_file[:type] || 'unknown',
-          "Security status" => "File validated and processed safely"
+          'Original filename' => filename,
+          'Sanitized filename' => safe_filename,
+          'Content type' => uploaded_file[:type] || 'unknown',
+          'Security status' => 'File validated and processed safely',
         }
 
-        info_html = file_info.map { |key, value|
+        info_html = file_info.map do |key, value|
           "<p><strong>#{key}:</strong> #{escape_html(value)}</p>"
-        }.join
+        end.join
 
         content = <<~HTML
-          #{otto_alert("success", "File Upload Successful", "File processed and validated successfully!")}
+          #{otto_alert('success', 'File Upload Successful', 'File processed and validated successfully!')}
 
-          #{otto_card("File Information") do
+          #{otto_card('File Information') do
             info_html
           end}
 
@@ -168,64 +173,62 @@ class SecureApp
           </div>
         HTML
       end
-
-    rescue Otto::Security::ValidationError => e
-      content = otto_alert("error", "File Validation Failed", e.message)
-    rescue => e
-      content = otto_alert("error", "Upload Error", "An error occurred during file upload.")
+    rescue Otto::Security::ValidationError => ex
+      content = otto_alert('error', 'File Validation Failed', ex.message)
+    rescue StandardError
+      content = otto_alert('error', 'Upload Error', 'An error occurred during file upload.')
     end
 
-    content += "<p class=\"otto-mt-lg\">#{otto_link("← Back to form", "/")}</p>"
-    res.body = otto_page(content, "Upload Response")
+    content += "<p class=\"otto-mt-lg\">#{otto_link('← Back to form', '/')}</p>"
+    res.body = otto_page(content, 'Upload Response')
   end
 
   def update_profile
     begin
-      name = req.params['name']
+      name  = req.params['name']
       email = req.params['email']
-      bio = req.params['bio']
+      bio   = req.params['bio']
 
       if respond_to?(:validate_input)
-        safe_name = validate_input(name, max_length: 100)
+        safe_name  = validate_input(name, max_length: 100)
         safe_email = validate_input(email, max_length: 255)
-        safe_bio = validate_input(bio, max_length: 500, allow_html: false)
+        safe_bio   = validate_input(bio, max_length: 500, allow_html: false)
       else
-        safe_name = name.to_s.strip[0..99]
+        safe_name  = name.to_s.strip[0..99]
         safe_email = email.to_s.strip[0..254]
-        safe_bio = bio.to_s.strip[0..499]
+        safe_bio   = bio.to_s.strip[0..499]
       end
 
       unless safe_email.match?(/\A[^@\s]+@[^@\s]+\z/)
-        raise Otto::Security::ValidationError, "Invalid email format"
+        raise Otto::Security::ValidationError, 'Invalid email format'
       end
 
       profile_data = {
-        "Name" => safe_name,
-        "Email" => safe_email,
-        "Bio" => safe_bio,
-        "Updated" => Time.now.strftime("%Y-%m-%d %H:%M:%S UTC")
+        'Name' => safe_name,
+        'Email' => safe_email,
+        'Bio' => safe_bio,
+        'Updated' => Time.now.strftime('%Y-%m-%d %H:%M:%S UTC'),
       }
 
-      profile_html = profile_data.map { |key, value|
+      profile_html = profile_data.map do |key, value|
         "<p><strong>#{key}:</strong> #{escape_html(value)}</p>"
-      }.join
+      end.join
 
       content = <<~HTML
-        #{otto_alert("success", "Profile Updated", "Your profile has been updated successfully!")}
+        #{otto_alert('success', 'Profile Updated', 'Your profile has been updated successfully!')}
 
-        #{otto_card("Profile Data") do
+        #{otto_card('Profile Data') do
           profile_html
         end}
       HTML
-
-    rescue Otto::Security::ValidationError => e
-      content = otto_alert("error", "Profile Validation Failed", e.message)
-    rescue => e
-      content = otto_alert("error", "Update Error", "An error occurred updating your profile.")
+    rescue Otto::Security::ValidationError => ex
+      content = otto_alert('error', 'Profile Validation Failed', ex.message)
+    rescue StandardError
+      content = otto_alert('error', 'Update Error', 'An error occurred updating your profile.')
     end
 
-    content += "<p class=\"otto-mt-lg\">#{otto_link("← Back to form", "/")}</p>"
-    res.body = otto_page(content, "Profile Update")
+    content += "<p class=\"otto-mt-lg\">#{otto_link('← Back to form', '/')}</p>"
+    res.body = otto_page(content, 'Profile Update')
   end
 
   def show_headers
@@ -239,16 +242,16 @@ class SecureApp
     end
 
     response_data = {
-      message: "Request headers analysis (filtered for security)",
+      message: 'Request headers analysis (filtered for security)',
       client_ip: req.respond_to?(:client_ipaddress) ? req.client_ipaddress : req.ip,
       secure_connection: req.respond_to?(:secure?) ? req.secure? : false,
       timestamp: Time.now.utc.iso8601,
       headers: safe_headers,
       security_analysis: {
-        csrf_protection: respond_to?(:csrf_token_valid?) ? "Active" : "Basic",
-        content_security: "Headers validated and filtered",
-        xss_protection: "HTML escaping enabled"
-      }
+        csrf_protection: respond_to?(:csrf_token_valid?) ? 'Active' : 'Basic',
+        content_security: 'Headers validated and filtered',
+        xss_protection: 'HTML escaping enabled',
+      },
     }
 
     require 'json'
@@ -257,17 +260,17 @@ class SecureApp
 
   def not_found
     res.status = 404
-    content = otto_alert("error", "Page Not Found", "The requested page could not be found.")
-    content += "<p>#{otto_link("← Back to home", "/")}</p>"
-    res.body = otto_page(content, "404 - Not Found")
+    content    = otto_alert('error', 'Page Not Found', 'The requested page could not be found.')
+    content   += "<p>#{otto_link('← Back to home', '/')}</p>"
+    res.body   = otto_page(content, '404 - Not Found')
   end
 
   def server_error
     res.status = 500
-    error_id = req.env['otto.error_id'] || SecureRandom.hex(8)
-    content = otto_alert("error", "Server Error", "An internal server error occurred.")
-    content += "<p><small>Error ID: #{escape_html(error_id)}</small></p>"
-    content += "<p>#{otto_link("← Back to home", "/")}</p>"
-    res.body = otto_page(content, "500 - Server Error")
+    error_id   = req.env['otto.error_id'] || SecureRandom.hex(8)
+    content    = otto_alert('error', 'Server Error', 'An internal server error occurred.')
+    content   += "<p><small>Error ID: #{escape_html(error_id)}</small></p>"
+    content   += "<p>#{otto_link('← Back to home', '/')}</p>"
+    res.body   = otto_page(content, '500 - Server Error')
   end
 end