ramaze 2010.06.18 → 2011.01

data/lib/ramaze/helper/cache.rb

@@ -66,11 +66,11 @@ module Ramaze
       # to do lazy computation of the cached value conveniently when using a
       # custom TTL or longer expressions that don't fit on one line with ||=.
       #
-      # @usage Example to get the cache object directly
+      # @example to get the cache object directly
       #
       #   count = cache_value[:count] ||= Article.count
       #
-      # @usage Example with block
+      # @example with block
       #
       #   count = cache_value(:count){ Article.count }
       #   count = cache_value(:count, :ttl => 60){ Article.count }

data/lib/ramaze/helper/csrf.rb

@@ -0,0 +1,225 @@
+require 'securerandom'
+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.
+    #
+    # 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:
+    #
+    #  class BaseController < Ramaze::Controller
+    #    before_all do
+    #      puts "Hello, before_all!"
+    #    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!
+    #
+    #  class BaseController < Ramaze::Controller
+    #    before_all do
+    #      csrf_protection :save do
+    #        # ....
+    #      end
+    #    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.
+    #
+    #  class BaseController < Ramaze::Controller
+    #    before_all do
+    #      csrf_protection :save do
+    #        puts "Hello, unsafe data!"
+    #      end
+    #    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.
+    #
+    # 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
+    #      csrf_protection :save do
+    #        respond("The supplied CSRF token is invalid.", 401)
+    #      end
+    #    end
+    #  end
+    #
+    # @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.
+      #
+      # @author Yorick Peterse
+      # @param  [Strings/Symbol] *methods Methods that will be protected/unprotected.
+      # @param  [Block] Block that will be executed if the token is invalid.
+      # @example
+      #
+      #  # Protect "create" and "save" against CSRF exploits
+      #  before_all do
+      #    csrf_protection :create, :save do
+      #      respond("GET TO DA CHOPPA!", 401)
+      #    end
+      #  end
+      #
+      def csrf_protection *methods, &block
+        # Only protect the specified methods
+        if methods.include?(action.name) or methods.include?(action.name.to_sym)
+          # 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
+        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:
+      #
+      # * 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. 
+      #
+      # @author Yorick Peterse
+      # @param  [Hash] Additional arguments that can be set such as the TTL.
+      # @return [Void]
+      #
+      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
+        session[:_csrf] = {
+          :time  => time.to_i,
+          :token => token,
+          :ip    => ip,
+          :agent => agent,
+          :host  => 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])
+          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:
+      #
+      # * 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.
+      #
+      # @author Yorick Peterse
+      # @param  [String] input_token The CSRF token to validate.
+      # @return [Bool]
+      # @example
+      #
+      #  before_all do
+      #    if validate_csrf_token(request.params['csrf_token']) != true
+      #      respond("Invalid CSRF token", 401)
+      #    end
+      #  end
+      #
+      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]
+        
+        # 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
+      end
+      
+    end # <-- End of CSRF module
+  end
+end

data/lib/ramaze/helper/erector.rb

@@ -5,15 +5,19 @@ require 'erector'
 
 module Ramaze
 
-  # Allows you to use some shortcuts for Erector in your Controller.
-
-  # use this inside your controller to directly build Erector 
-  # Refer to the Erector-documentation and testsuite for more examples.
-  # Usage:
-  #   erector { h1 "Apples & Oranges" }                           #=> "<h1>Apples &amp; Oranges</h1>"
-  #   erector { h1(:class => 'fruits&floots'){ text 'Apples' } }  #=> "<h1 class=\"fruits&amp;floots\">Apples</h1>"
-
   module Helper
+    
+    ##
+    # Allows you to use some shortcuts for Erector in your Controller.
+    #
+    # use this inside your controller to directly build Erector 
+    # 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>"
+    #
     module Erector
       include ::Erector::Mixin
 
@@ -21,27 +25,81 @@ module Ramaze
         alias :raw! :rawtext
         alias :old_css :css
 
+        ##
+        # Method that generates a XHTML 1.0 Strict doctype.
+        #
+        # @example
+        #
+        #   strict_html do
+        #     head do
+        #       title "Ramaze Rocks!"
+        #     end
+        #     body
+        #       div do
+        #         
+        #       end
+        #     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.
+        #
         def strict_xhtml(*args, &block)
           raw! '<?xml version="1.0" encoding="UTF-8"?>'
           raw! '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">'
           html(:xmlns => "http://www.w3.org/1999/xhtml", :"xml:lang" => "en", :lang => "en", &block)
         end
 
+        ##
+        # Generate a Javascript tag.
+        #
+        # @example
+        # 
+        #   js 'javascript/jquery.js'
+        #
+        # @param [String] src The full or relative path to the Javascript file.
+        #
         def js(src)
           script :src => src
         end
 
+        ##
+        # Generate a pair of conditional tags for a specific browser.
+        #
+        # @example
+        #
+        #   ie_if 'IE' do
+        #     ......
+        #   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.
+        #
         def ie_if(expr, &block)
           raw! "<!--[if #{expr}]>"
           yield
           raw! "<![endif]-->"
         end
 
-        # Diagnostics
+        ##
+        # Inspect the specified element.
+        #
+        # @param [String] elem The element to inspect.
+        #
         def inspect(elem)
           text elem.inspect
         end
 
+        ##
+        # Generate a stylesheet tag.
+        #
+        # @example
+        #
+        #   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.
+        #
         def css(href, args = {})
           attrs = {
             :rel => "stylesheet", 

data/lib/ramaze/helper/flash.rb

@@ -14,7 +14,7 @@ module Ramaze
   # On the first request, for example on registering:
   #
   #   flash[:error] = "You should reconsider your username, it's taken already"
-  #   redirect R(self, :register)
+  #   redirect r(:register)
   #
   # This is the request from the redirect:
   #
@@ -28,7 +28,9 @@ module Ramaze
 
       trait :flashbox => "<div class='flash' id='flash_%key'>%value</div>"
 
-      # answers with Current.session.flash
+      ##
+      # Return the current value of Current.session.flash
+      #
       def flash
         Current.session.flash
       end

data/lib/ramaze/helper/gestalt.rb

@@ -2,6 +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.
     module Gestalt
       CACHE_G = {}
 

data/lib/ramaze/helper/gravatar.rb

@@ -50,7 +50,7 @@ module Ramaze
       #   Fall back to default if the given +email+ doesn't have an gravatar;
       #   may be an absolute url, 'identicon', 'monsterid', or 'wavatar'
       #
-      # @options opts [true, false] :force (false)
+      # @option opts [true, false] :force (false)
       #   Force use of the default avatar, useful if you want to use only
       #   identicons or the like
       #

data/lib/ramaze/helper/localize.rb

@@ -3,6 +3,10 @@ require 'locale'
 
 module Ramaze
   module Helper
+    ##
+    # The localization helper can be used to output translated strings.
+    # This enables your application to use multiple language files for English, Dutch and so on.
+    #
     module Localize
       include Traited
 

data/lib/ramaze/helper/send_file.rb

@@ -0,0 +1,30 @@
+module Ramaze
+  module Helper
+    ##
+    # The SendFile module can be used to stream a file to the user's computer.
+    # While the performance of the module isn't optimal it's convenient and relatively easy to use.
+    #
+    module SendFile
+      ##
+      # The send_file method streams the specified file to the user's browser.
+      #
+      # @param [String] filename The name or path to the file which will be streamed to the user.
+      # @param [String] content_type The type of file we're dealing with. For example, if we want to stream
+      # a JPG image we'd set this variable to 'image/jpg'.
+      # @param [String] content_disposition Value for the Content-Disposition header.
+      #
+      def send_file(filename, content_type = nil, content_disposition = nil)
+        content_type ||= Rack::Mime.mime_type(::File.extname(filename))
+        content_disposition ||= File.basename(filename)
+
+        response.body = ::File.open(filename, 'rb')
+        response['Content-Length'] = ::File.size(filename).to_s
+        response['Content-Type'] = content_type
+        response['Content-Disposition'] = content_disposition
+        response.status = 200
+
+        throw(:respond, response)
+      end
+    end
+  end
+end

data/lib/ramaze/helper/thread.rb

@@ -3,6 +3,11 @@
 
 module Ramaze
   module Helper::Thread
+    ##
+    # The thread method executes the specified block in a new thread.
+    #
+    # @param [Block] block The block that contains the code that will be executed in the new thread.
+    #
     def thread &block
       parent_thread = Thread.current
       Thread.new do