joe-merb-core 0.9.8

data/lib/merb-core/dispatch/session.rb

@@ -0,0 +1,222 @@
+require 'merb-core/dispatch/session/container'
+require 'merb-core/dispatch/session/store_container'
+
+module Merb
+  class Config
+    # Returns stores list constructed from
+    # configured session stores (:session_stores config option)
+    # or default one (:session_store config option).
+    def self.session_stores
+      @session_stores ||= begin
+        config_stores = Array(
+          Merb::Config[:session_stores] || Merb::Config[:session_store]
+        )
+        config_stores.map { |name| name.to_sym }
+      end
+    end
+  end # Config
+
+  # The Merb::Session module gets mixed into Merb::SessionContainer to allow
+  # app-level functionality (usually found in app/models/merb/session.rb) for
+  # session.
+  #
+  # You can use this module to implement additional methods to simplify
+  # building wizard-like application components,
+  # authentication frameworks, etc.
+  module Session
+  end
+
+  # This is mixed into Merb::Controller on framework boot.
+  module SessionMixin
+    # Raised when no suitable session store has been setup.
+    class NoSessionContainer < StandardError; end
+
+    # Raised when storing more data than the available space reserved.
+    class SessionOverflow < StandardError; end
+
+    # Session configuration options:
+    #
+    # :session_id_key           The key by which a session value/id is
+    #                           retrieved; defaults to _session_id
+    #
+    # :session_expiry           When to expire the session cookie;
+    #                           defaults to 2 weeks
+    #
+    # :session_secret_key       A secret string which is used to sign/validate
+    #                           session data; min. 16 chars
+    #
+    # :default_cookie_domain    The default domain to write cookies for.
+    def self.included(base)
+      # Register a callback to finalize sessions - needs to run before the cookie
+      # callback extracts Set-Cookie headers from request.cookies.
+      base._after_dispatch_callbacks.unshift lambda { |c| c.request.finalize_session }
+    end
+
+    # ==== Parameters
+    # session_store<String>:: The type of session store to access.
+    #
+    # ==== Returns
+    # SessionContainer:: The session that was extracted from the request object.
+    def session(session_store = nil)
+      request.session(session_store)
+    end
+
+    # Module methods
+
+    # ==== Returns
+    # String:: A random 32 character string for use as a unique session ID.
+    def rand_uuid
+      values = [
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x0010000),
+        rand(0x1000000),
+        rand(0x1000000),
+      ]
+      "%04x%04x%04x%04x%04x%06x%06x" % values
+    end
+
+    # Marks this session as needing a new cookie.
+    def needs_new_cookie!
+      @_new_cookie = true
+    end
+
+    def needs_new_cookie?
+      @_new_cookie
+    end
+
+    module_function :rand_uuid, :needs_new_cookie!, :needs_new_cookie?
+
+    module RequestMixin
+
+      def self.included(base)
+        base.extend ClassMethods
+
+        # Keep track of all known session store types.
+        base.cattr_accessor :registered_session_types
+        base.registered_session_types = Dictionary.new
+        base.class_inheritable_accessor :_session_id_key, :_session_secret_key,
+                                        :_session_expiry
+
+        base._session_id_key        = Merb::Config[:session_id_key] || '_session_id'
+        base._session_expiry        = Merb::Config[:session_expiry] || 0
+        base._session_secret_key    = Merb::Config[:session_secret_key]
+      end
+
+      module ClassMethods
+
+        # ==== Parameters
+        # name<~to_sym>:: Name of the session type to register.
+        # class_name<String>:: The corresponding class name.
+        #
+        # === Notres
+        # This is automatically called when Merb::SessionContainer is subclassed.
+        def register_session_type(name, class_name)
+          self.registered_session_types[name.to_sym] = class_name
+        end
+
+      end
+
+      # The default session store type.
+      def default_session_store
+        Merb::Config[:session_store] && Merb::Config[:session_store].to_sym
+      end
+
+      # ==== Returns
+      # Hash:: All active session stores by type.
+      def session_stores
+        @session_stores ||= {}
+      end
+
+      # Returns session container. Merb is able to handle multiple session
+      # stores, hence a parameter to pick it.
+      #
+      # ==== Parameters
+      # session_store<String>:: The type of session store to access,
+      # defaults to default_session_store.
+      #
+      # === Notes
+      # If no suitable session store type is given, it defaults to
+      # cookie-based sessions.
+      def session(session_store = nil)
+        session_store ||= default_session_store
+        if class_name = self.class.registered_session_types[session_store]
+          session_stores[session_store] ||= Object.full_const_get(class_name).setup(self)
+        elsif fallback = self.class.registered_session_types.keys.first
+          Merb.logger.warn "Session store '#{session_store}' not found. Check your configuration in init file."
+          Merb.logger.warn "Falling back to #{fallback} session store."
+          session(fallback)
+        else
+          msg = "No session store set. Set it in init file like this: c[:session_store] = 'activerecord'"
+          Merb.logger.error!(msg)
+          raise NoSessionContainer, msg            
+        end
+      end
+
+      # ==== Parameters
+      # new_session<Merb::SessionContainer>:: A session store instance.
+      #
+      # === Notes
+      # The session is assigned internally by its session_store_type key.
+      def session=(new_session)
+        if self.session?(new_session.class.session_store_type)
+          original_session_id = self.session(new_session.class.session_store_type).session_id
+          if new_session.session_id != original_session_id
+            set_session_id_cookie(new_session.session_id)
+          end
+        end
+        session_stores[new_session.class.session_store_type] = new_session
+      end
+
+      # Whether a session has been setup
+      def session?(session_store = nil)
+        (session_store ? [session_store] : session_stores).any? do |type, store|
+          store.is_a?(Merb::SessionContainer)
+        end
+      end
+
+      # Teardown and/or persist the current sessions.
+      def finalize_session
+        session_stores.each { |name, store| store.finalize(self) }
+      end
+      alias :finalize_sessions :finalize_session
+
+      # Assign default cookie values
+      def default_cookies
+        defaults = {}
+        if route && route.allow_fixation? && params.key?(_session_id_key)
+          Merb.logger.info("Fixated session id: #{_session_id_key}")
+          defaults[_session_id_key] = params[_session_id_key]
+        end
+        defaults
+      end
+
+      # Sets session cookie value.
+      #
+      # ==== Parameters
+      # value<String>:: The value of the session cookie; either the session id or the actual encoded data.
+      # options<Hash>:: Cookie options like domain, path and expired.
+      def set_session_cookie_value(value, options = {})
+        defaults = {}
+        defaults[:expires] = Time.now + _session_expiry if _session_expiry > 0
+        cookies.set_cookie(_session_id_key, value, defaults.merge(options))
+      end
+      alias :set_session_id_cookie :set_session_cookie_value
+
+      # ==== Returns
+      # String:: The value of the session cookie; either the session id or the actual encoded data.
+      def session_cookie_value
+        cookies[_session_id_key]
+      end
+      alias :session_id :session_cookie_value
+      
+      # Destroy the session cookie.
+      def destroy_session_cookie
+        cookies.delete(_session_id_key)
+      end
+      
+    end
+  end
+end

data/lib/merb-core/dispatch/session/container.rb

@@ -0,0 +1,74 @@
+module Merb
+  class SessionContainer < Mash
+  
+    class_inheritable_accessor :session_store_type
+    cattr_accessor :subclasses 
+    self.subclasses = []
+  
+    attr_reader :session_id
+    attr_accessor :needs_new_cookie
+  
+    class << self
+  
+      # Register the subclass as an available session store type.
+      def inherited(klass)
+        self.subclasses << klass.to_s
+        super
+      end
+
+      # Generates a new session ID and creates a new session.
+      #
+      # ==== Returns
+      # SessionContainer:: The new session.
+      def generate
+      end
+    
+      # ==== Parameters
+      # request<Merb::Request>:: The Merb::Request that came in from Rack.
+      #
+      # ==== Returns
+      # SessionContainer:: a SessionContainer. If no sessions were found, 
+      # a new SessionContainer will be generated.
+      def setup(request)
+      end    
+    
+    end
+  
+    # ==== Parameters
+    # session_id<String>:: A unique identifier for this session.
+    def initialize(session_id)
+      @_destroy = false
+      self.session_id = session_id
+    end
+    
+    # Assign a new session_id.
+    #
+    # Recreates the cookie with the default expiration time. Useful during log
+    # in for pushing back the expiration date.
+    def session_id=(sid)
+      self.needs_new_cookie = (@session_id && @session_id != sid)
+      @session_id = sid
+    end
+  
+    # Teardown and/or persist the current session.
+    #
+    # If @_destroy is true, clear out the session completely, including
+    # removal of the session cookie itself.
+    #
+    # ==== Parameters
+    # request<Merb::Request>:: The Merb::Request that came in from Rack.
+    def finalize(request)
+    end
+  
+    # Destroy the current session - clears data and removes session cookie.
+    def clear!
+      @_destroy = true
+      self.clear
+    end
+  
+    # Regenerate the session_id.
+    def regenerate
+    end
+
+  end
+end

data/lib/merb-core/dispatch/session/cookie.rb

@@ -0,0 +1,173 @@
+require 'base64'        # to convert Marshal.dump to ASCII
+require 'openssl'       # to generate the HMAC message digest
+module Merb
+
+  # If you have more than 4K of session data or don't want your data to be
+  # visible to the user, pick another session store.
+  #
+  # CookieOverflow is raised if you attempt to store more than 4K of data.
+  # TamperedWithCookie is raised if the data integrity check fails.
+  #
+  # A message digest is included with the cookie to ensure data integrity:
+  # a user cannot alter session data without knowing the secret key included
+  # in the hash.
+  #
+  # To use Cookie Sessions, set in config/merb.yml
+  #  :session_secret_key - your secret digest key
+  #  :session_store: cookie
+  class CookieSession < SessionContainer
+    # TODO (maybe):
+    # include request ip address
+    # AES encrypt marshaled data
+
+    # Raised when storing more than 4K of session data.
+    class CookieOverflow < StandardError; end
+
+    # Raised when the cookie fails its integrity check.
+    class TamperedWithCookie < StandardError; end
+
+    # Cookies can typically store 4096 bytes.
+    MAX = 4096
+    DIGEST = OpenSSL::Digest::Digest.new('SHA1') # or MD5, RIPEMD160, SHA256?
+
+    attr_accessor :_original_session_data
+
+    # The session store type
+    self.session_store_type = :cookie
+
+    class << self
+      # Generates a new session ID and creates a new session.
+      #
+      # ==== Returns
+      # SessionContainer:: The new session.
+      def generate
+        self.new(Merb::SessionMixin.rand_uuid, "", Merb::Request._session_secret_key)
+      end
+
+      # Set up a new session on request: make it available on request instance.
+      #
+      # ==== Parameters
+      # request<Merb::Request>:: The Merb::Request that came in from Rack.
+      #
+      # ==== Returns
+      # SessionContainer:: a SessionContainer. If no sessions were found,
+      # a new SessionContainer will be generated.
+      def setup(request)
+        session = self.new(Merb::SessionMixin.rand_uuid,
+          request.session_cookie_value, request._session_secret_key)
+        session._original_session_data = session.to_cookie
+        request.session = session
+      end
+
+    end
+
+    # ==== Parameters
+    # session_id<String>:: A unique identifier for this session.
+    # cookie<String>:: The raw cookie data.
+    # secret<String>:: A session secret.
+    #
+    # ==== Raises
+    # ArgumentError:: Nil or blank secret.
+    def initialize(session_id, cookie, secret)
+      super session_id
+      if secret.blank? || secret.length < 16
+        msg = "You must specify a session_secret_key in your init file, and it must be at least 16 characters"
+        Merb.logger.warn(msg)
+        raise ArgumentError, msg
+      end
+      @secret = secret
+      self.update(unmarshal(cookie))
+    end
+
+    # Teardown and/or persist the current session.
+    #
+    # If @_destroy is true, clear out the session completely, including
+    # removal of the session cookie itself.
+    #
+    # ==== Parameters
+    # request<Merb::Request>:: request object created from Rack environment.
+    def finalize(request)
+      if @_destroy
+        request.destroy_session_cookie
+      elsif _original_session_data != (new_session_data = self.to_cookie)
+        request.set_session_cookie_value(new_session_data)
+      end
+    end
+    
+    # Regenerate the session_id.
+    def regenerate
+      self.session_id = Merb::SessionMixin.rand_uuid
+    end
+
+    # Create the raw cookie string; includes an HMAC keyed message digest.
+    #
+    # ==== Returns
+    # String:: Cookie value.
+    #
+    # ==== Raises
+    # CookieOverflow:: More than 4K of data put into session.
+    #
+    # ==== Notes
+    # Session data is converted to a Hash first, since a container might
+    # choose to marshal it, which would make it persist
+    # attributes like 'needs_new_cookie', which it shouldn't.
+    def to_cookie
+      unless self.empty?
+        data = self.serialize
+        value = Merb::Request.escape "#{data}--#{generate_digest(data)}"
+        if value.size > MAX
+          msg = "Cookies have limit of 4K. Session contents: #{data.inspect}"
+          Merb.logger.error!(msg)
+          raise CookieOverflow, msg
+        end
+        value
+      end
+    end
+
+    private
+
+    # Generate the HMAC keyed message digest. Uses SHA1.
+    def generate_digest(data)
+      OpenSSL::HMAC.hexdigest(DIGEST, @secret, data)
+    end
+
+    # Unmarshal cookie data to a hash and verify its integrity.
+    #
+    # ==== Parameters
+    # cookie<~to_s>:: The cookie to unmarshal.
+    #
+    # ==== Raises
+    # TamperedWithCookie:: The digests don't match.
+    #
+    # ==== Returns
+    # Hash:: The stored session data.
+    def unmarshal(cookie)
+      if cookie.blank?
+        {}
+      else
+        data, digest = Merb::Request.unescape(cookie).split('--')
+        return {} if data.blank? || digest.blank?
+        unless digest == generate_digest(data)
+          clear
+          unless Merb::Config[:ignore_tampered_cookies]
+            raise TamperedWithCookie, "Maybe the site's session_secret_key has changed?"
+          end
+        end
+        unserialize(data)
+      end
+    end
+
+    protected
+
+    # Serialize current session data as a Hash.
+    # Uses Base64 encoding for integrity.
+    def serialize
+      Base64.encode64(Marshal.dump(self.to_hash)).chop
+    end
+
+    # Unserialize the raw cookie data to a Hash
+    def unserialize(data)
+      Marshal.load(Base64.decode64(data)) rescue {}
+    end
+  end
+end