ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/helper/csrf.rb

@@ -4,20 +4,24 @@ require 'digest'
 module Ramaze
   module Helper
     ##
-    # A relatively basic yet useful helper that can be used to protect your application
-    # from CSRF attacks/exploits. Note that this helper merely generates the required data,
-    # and provides several methods. You still need to manually add the token to each form.
+    # A relatively basic yet useful helper that can be used to protect your
+    # application from CSRF attacks/exploits. Note that this helper merely
+    # generates the required data, and provides several methods. You still need
+    # to manually add the token to each form.
     #
-    # The reason for this is because this is quite simple. Ramaze is meant as a framework that
-    # works with any given helper, ORM, template engine and so on. If we were to automatically
-    # load this helper and include (a perhaps more advanced) CSRF system that would mean that
-    # every form helper, official or third-party, would have to support that specific system.
-    # However, there's no need to panic as it's very easy to setup a basic anti CSRF system.
+    # The reason for this is because this is quite simple. Ramaze is meant as a
+    # framework that works with any given helper, ORM, template engine and so
+    # on. If we were to automatically load this helper and include (a perhaps
+    # more advanced) CSRF system that would mean that every form helper,
+    # official or third-party, would have to support that specific system.
+    # However, there's no need to panic as it's very easy to setup a basic anti
+    # CSRF system.
     #
     # == Usage
     #
-    # In order to enable CSRF protection we need to do two things. Load the helper and create
-    # a before_all block in a controller. Take a look at the following code:
+    # In order to enable CSRF protection we need to do two things. Load the
+    # helper and create a before_all block in a controller. Take a look at the
+    # following code:
     #
     #  class BaseController < Ramaze::Controller
     #    before_all do
@@ -25,8 +29,9 @@ module Ramaze
     #    end
     #  end
     #
-    # This would output "Hello, before_all!" to the console upon each request. Not very useful
-    # but it does show what the before_all block can do. On to actual CSRF related code!
+    # This would output "Hello, before_all!" to the console upon each request.
+    # Not very useful but it does show what the before_all block can do. On to
+    # actual CSRF related code!
     #
     #  class BaseController < Ramaze::Controller
     #    before_all do
@@ -36,10 +41,11 @@ module Ramaze
     #    end
     #  end
     #
-    # This example introduces an extra block that validates the current request.
-    # Whenever a user requests a controller that either extends BaseController or has it's own
-    # before_all block Ramaze will check if the current request data contains a CSRF token.
-    # Of course an if/end isn't very useful if it doesn't do anything, let's add some code.
+    # This example introduces an extra block that validates the current
+    # request. Whenever a user requests a controller that either extends
+    # BaseController or has it's own before_all block Ramaze will check if the
+    # current request data contains a CSRF token. Of course an if/end isn't
+    # very useful if it doesn't do anything, let's add some code.
     #
     #  class BaseController < Ramaze::Controller
     #    before_all do
@@ -49,14 +55,17 @@ module Ramaze
     #    end
     #  end
     #
-    # The code above checks if the current method is "save" (or any other of the provided methods)
-    # and checks if an CSRF token is supplied if the method matches. Protected methods require
-    # a token in ALL HTTP requests (GET, POST, etc). While this may seem weird since GET is generally
-    # used for safe actions it actually makes sence. Ramaze stores both the POST and GET parameters in
-    # the request.params hash. While this makes it easy to work with POST/GET data this also makes it
-    # easier to spoof POST requests using a GET request, thus this helper protects ALL request methods.
+    # The code above checks if the current method is "save" (or any other of
+    # the provided methods) and checks if an CSRF token is supplied if the
+    # method matches. Protected methods require a token in ALL HTTP requests
+    # (GET, POST, etc). While this may seem weird since GET is generally used
+    # for safe actions it actually makes sense. Ramaze stores both the POST and
+    # GET parameters in the request.params hash. While this makes it easy to
+    # work with POST/GET data this also makes it easier to spoof POST requests
+    # using a GET request, thus this helper protects ALL request methods.
     #
-    # If you're a lazy person you can copy-paste the example below and adapt it to your needs.
+    # If you're a lazy person you can copy-paste the example below and adapt it
+    # to your needs.
     #
     #  class BaseController < Ramaze::Controller
     #    before_all do
@@ -69,11 +78,12 @@ module Ramaze
     # @author Yorick Peterse
     #
     module CSRF
-      
+
       ##
-      # Method that can be used to protect the specified methods against CSRF exploits.
-      # Each protected method will require the token to be stored in a field called "csrf_token".
-      # This method will then validate that token against the current token in the session.
+      # Method that can be used to protect the specified methods against CSRF
+      # exploits. Each protected method will require the token to be stored in
+      # a field called "csrf_token". This method will then validate that token
+      # against the current token in the session.
       #
       # @author Yorick Peterse
       # @param  [Strings/Symbol] *methods Methods that will be protected/unprotected.
@@ -93,22 +103,20 @@ module Ramaze
           # THINK: For now the field name is hard-coded to "csrf_token". While
           # this is perfectly fine in most cases it might be a good idea
           # to allow developers to change the name of this field (for whatever the reason).
-          if validate_csrf_token(request.params['csrf_token']) != true
-            yield
-          end
+          yield unless validate_csrf_token(request.params['csrf_token'])
         end
       end
-      
+
       ##
-      # Generate a new token and create the session array that will be used to validate the client.
-      # The following items are stored in the session:
+      # Generate a new token and create the session array that will be used to
+      # validate the client. The following items are stored in the session:
       #
       # * token: An unique hash that will be stored in each form
       # * agent: The visitor's user agent
       # * ip: The IP address of the visitor
       # * time: Timestamp that indicates at what time the data was generated.
       #
-      # Note that this method will be automatically called if no CSRF token exists. 
+      # Note that this method will be automatically called if no CSRF token exists.
       #
       # @author Yorick Peterse
       # @param  [Hash] Additional arguments that can be set such as the TTL.
@@ -116,66 +124,59 @@ module Ramaze
       #
       def generate_csrf_token args = {}
         # Default TTL is 15 minutes
-        if args[:ttl]
-          ttl = args[:ttl]
-        else
-          ttl = 900
-        end
-        
-        # Generate all the required data
-        time    = Time.new.to_i.to_s
-        number  = SecureRandom.random_number(10000).to_s
-        base64  = SecureRandom.base64.to_s
-        token   = Digest::SHA2.new(512).hexdigest(srand.to_s + rand.to_s + time + number + base64).to_s
-        
-        # Get several details from the client such as the user agent, IP, etc
-        ip      = request.env['REMOTE_ADDR']
-        agent   = request.env['HTTP_USER_AGENT']
-        host    = request.env['REMOTE_HOST']
-        
-        # Time to store all the data
+        ttl = args[:ttl] || (15 * 60)
+
+        # Get some good entropy
+        random = SecureRandom.random_bytes(512)
+        # and some not so good entropy
+        time = Time.now.to_f
+
+        # Hash it together
+        token = Digest::SHA512.hexdigest(random + time.to_s)
+
+        # Time to store all the data we want to check later.
         session[:_csrf] = {
           :time  => time.to_i,
           :token => token,
-          :ip    => ip,
-          :agent => agent,
-          :host  => host,
+          :ip    => request.env['REMOTE_ADDR'],
+          :agent => request.env['HTTP_USER_AGENT'],
+          :host  => request.env['REMOTE_HOST'],
           :ttl   => ttl
         }
-        
+
         # Prevent this method from returning any value (it isn't needed anyway)
         return
       end
-      
+
       ##
       # Retrieves the current value of the CSRF token.
       #
       # @author Yorick Peterse
       # @return [String] The current CSRF token.
       # @example
-      # 
+      #
       #  form(@data, :method => :post) do |f|
       #    f.input_hidden :csrf_token, get_csrf_token()
       #  end
       #
       def get_csrf_token
-        if !session[:_csrf] or !self.validate_csrf_token(session[:_csrf][:token])
+        if !session[:_csrf] || !self.validate_csrf_token(session[:_csrf][:token])
           self.generate_csrf_token
         end
-        
+
         # Land ho!
         return session[:_csrf][:token]
       end
-      
+
       ##
-      # Validates the request based on the current session date stored in _csrf.
-      # The following items are verified:
+      # Validates the request based on the current session date stored in
+      # _csrf. The following items are verified:
       #
       # * Do the user agent, ip and token match those supplied by the visitor?
       # * Has the token been expired? (after 15 minutes).
       #
-      # If any of these checks fail this method will return FALSE. It's your job to
-      # take action based on the results of this method.
+      # If any of these checks fail this method will return FALSE. It's your
+      # job to take action based on the results of this method.
       #
       # @author Yorick Peterse
       # @param  [String] input_token The CSRF token to validate.
@@ -188,38 +189,22 @@ module Ramaze
       #    end
       #  end
       #
-      def validate_csrf_token input_token
+      def validate_csrf_token(input_token)
         # Check if the CSRF data has been generated and generate it if this
         # hasn't been done already (usually on the first request).
         if !session[:_csrf] or session[:_csrf].empty?
           self.generate_csrf_token
         end
-        
-        # Get several details from the client such as the user agent, IP, etc
-        ip      = session[:_csrf][:ip]
-        agent   = session[:_csrf][:agent]
-        host    = session[:_csrf][:host]
-        
-        # Get the current time and the time when the token was created
-        now         = Time.new.to_i
-        token_time  = session[:_csrf][:time]
-        
+
+        _csrf = session[:_csrf]
+
         # Mirror mirror on the wall, who's the most secure of them all?
-        results     = Array.new
-        results.push( session[:_csrf][:token] == input_token )
-        results.push( (now  - token_time) <= session[:_csrf][:ttl] )
-        results.push( host  == request.env['REMOTE_HOST'] )
-        results.push( ip    == request.env['REMOTE_ADDR'] )
-        results.push( agent == request.env['HTTP_USER_AGENT'] )
-        
-        # Verify the results
-        if results.include?(false)
-          return false
-        else
-          return true
-        end
+        session[:_csrf][:token] == input_token &&
+          (Time.now.to_f - _csrf[:time]) <= _csrf[:ttl] &&
+          _csrf[:host] == request.env['REMOTE_HOST'] &&
+          _csrf[:ip] == request.env['REMOTE_ADDR'] &&
+          _csrf[:agent] == request.env['HTTP_USER_AGENT']
       end
-      
-    end # <-- End of CSRF module
+    end
   end
 end

data/lib/ramaze/helper/email.rb

@@ -0,0 +1,105 @@
+require 'net/smtp'
+
+module Ramaze
+  module Helper
+    ##
+    # The Email helper can be used as a simple way of sending Emails from your
+    # application. In order to use this helper you first need to load it:
+    #
+    #  class Comments < Ramaze::Controller
+    #    helper :email
+    #  end
+    #
+    # Sending an Email can be done by calling the method send_email():
+    #
+    #  send_email('info@yorickpeterse.com', 'Hello, world!', 'Hello, this is an Email')
+    #
+    # Ramaze will log any errors in case the Email could not be sent so you don't have to
+    # worry about this.
+    #
+    # == Options
+    #
+    # This module can be configured using Innate::Optioned. Say you want to change the
+    # SMTP host you simply need to do the following:
+    #
+    #  Ramaze::Helper::Email.options.host = 'mail.google.com'
+    #
+    # Various other options are available, for a full list of these options run the
+    # following in an IRB session:
+    #
+    #  puts Ramaze::Helper::Email.options
+    #
+    # By default this helper uses \r\n for newlines, this can be changed as following:
+    #
+    #  Ramaze::Helper::Email.options.newline = "\n"
+    #
+    # It's important that this setting matches the settings of your SMTP server as
+    # otherwise you (usually) won't be able to send any Emails.
+    #
+    # @author Yorick Peterse
+    # @author Michael Fellinger
+    # @since  16-06-2011
+    #
+    module Email
+      include Innate::Optioned
+
+      options.dsl do
+        o 'The SMTP server to use for sending Emails'     , :host          , ''
+        o 'The SMTP helo domain'                          , :helo_domain   , ''
+        o 'The username for the SMTP server'              , :username      , ''
+        o 'The password for the SMTP server'              , :password      , ''
+        o 'The sender\'s Email address'                   , :sender        , ''
+        o 'The port of the SMTP server'                   , :port          , 25
+        o 'The authentication type of the SMTP server'    , :auth_type     , :login
+        o 'An array of addresses to forward the Emails to', :bcc           , []
+        o 'The name (including the Email) of the sender'  , :sender_full   , nil
+        o 'A prefix to use for the subjects of the Emails', :subject_prefix, ''
+        o 'The type of newlines to use for the Email'     , :newline       , "\r\n"
+        o 'The generator to use for Email IDs'            , :generator     , lambda {
+          "<" + Time.now.to_i.to_s + "@" + Ramaze::Helper::Email.options.helo_domain + ">"
+        }
+      end
+      
+      ##
+      # Sends an Email over SMTP.
+      #
+      # @example
+      #  send_email('info@yorickpeterse.com', 'Hello, world!', 'Hello, this is an Email')
+      #
+      # @author Yorick Peterse
+      # @author Michael Fellinger
+      # @since  16-06-2011
+      # @param  [String] recipient The Email address to send the Email to.
+      # @param  [String] subject The subject of the Email.
+      # @param  [String] message The body of the Email
+      #
+      def send_email(recipient, subject, message)
+        sender  = Email.options.sender_full || "#{Email.options.sender} <#{Email.options.sender}>"
+        subject = [Email.options.subject_prefix, subject].join(' ').strip
+        id      = Email.options.generator.call
+
+        # Generate the body of the Email
+        email   = [
+          "From: #{sender}", "To: <#{recipient}>", "Date: #{Time.now.rfc2822}",
+          "Subject: #{subject}", "Message-Id: #{id}", '', message
+        ].join(Email.options.newline)
+
+        # Send the Email
+        email_options = []
+
+        [:host, :port, :helo_domain, :username, :password, :auth_type].each do |k|
+          email_options.push(Email.options[k])
+        end
+
+        begin
+          Net::SMTP.start(*email_options) do |smtp|
+            smtp.send_message(email, Email.options.sender, [recipient, *Email.options.bcc])
+            Ramaze::Log.info("Email sent to #{recipient} with subject \"#{subject}\"")
+          end
+        rescue => e
+          Ramaze::Log.error("Failed to send an Email to #{recipient}: #{e.inspect}")
+        end
+      end
+    end # Email
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/erector.rb

@@ -4,9 +4,7 @@
 require 'erector'
 
 module Ramaze
-
   module Helper
-    
     ##
     # Allows you to use some shortcuts for Erector in your Controller.
     #
@@ -14,9 +12,8 @@ module Ramaze
     # Refer to the Erector-documentation and testsuite for more examples.
     #
     # @example
-    #
-    #   erector { h1 "Apples & Oranges" }                           #=> "<h1>Apples &amp; Oranges</h1>"
-    #   erector { h1(:class => 'fruits&floots'){ text 'Apples' } }  #=> "<h1 class=\"fruits&amp;floots\">Apples</h1>"
+    #   erector { h1 "Apples & Oranges" } #=> "<h1>Apples &amp; Oranges</h1>"
+    #   erector { h1(:class => 'fruits&floots'){ text 'Apples' } }
     #
     module Erector
       include ::Erector::Mixin
@@ -41,8 +38,10 @@ module Ramaze
         #     end
         #   end
         #
-        # @param [Hash] args Hash containing extra options such as the xml:lang and xmlns attribute.
-        # @param [Block] block Block that contains the inner data of the <html> element.
+        # @param [Hash] args Hash containing extra options such as the xml:lang 
+        #  and xmlns attribute.
+        # @param [Block] block Block that contains the inner data of the <html>
+        #  element.
         #
         def strict_xhtml(*args, &block)
           raw! '<?xml version="1.0" encoding="UTF-8"?>'
@@ -73,7 +72,8 @@ module Ramaze
         #   end
         #
         # @param [String] expr The if expression, such as 'IE' or 'lte IE7'.
-        # @param [block] block Block that contains the data that needs to be loaded for the specified browser.
+        # @param [block] block Block that contains the data that needs to be 
+        #  loaded for the specified browser.
         #
         def ie_if(expr, &block)
           raw! "<!--[if #{expr}]>"
@@ -97,8 +97,10 @@ module Ramaze
         #
         #   css 'css/reset.css', :media => 'print'
         #
-        # @param [String] href The path (either absolute or relative) to the CSS file.
-        # @param [Hash] args A hash containing additional arguments to add to the CSS tag.
+        # @param [String] href The path (either absolute or relative) to the CSS 
+        #  file.
+        # @param [Hash] args A hash containing additional arguments to add to 
+        #  the CSS tag.
         #
         def css(href, args = {})
           attrs = {
@@ -109,8 +111,7 @@ module Ramaze
 
           link attrs
         end
-      end
-    end
-  end
-end
-
+      end # Erector::Widget
+    end # Erector
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/gestalt.rb

@@ -2,8 +2,8 @@ require 'ramaze/gestalt'
 
 module Ramaze
   module Helper
-    ##
-    # Gestalt is the custom HTML/XML builder for Ramaze, based on a very simple DSL it will build your markup.
+    # Gestalt is the custom HTML/XML builder for Ramaze, based on a very simple 
+    # DSL it will build your markup.
     module Gestalt
       CACHE_G = {}