tynn 1.4.0 → 2.0.0.alpha

data/lib/tynn/session.rb

@@ -1,21 +1,23 @@
+# frozen_string_literal: true
+
 class Tynn
-  # Public: Adds simple cookie based session management. You can pass a secret
+  # Adds simple cookie based session management. You can pass a secret
   # token to sign the cookie data, thus unauthorized means can't alter it.
   #
-  # Examples
-  #
   #   require "tynn"
   #   require "tynn/session"
   #
-  #   Tynn.plugin(Tynn::Session, secret: "__change_me__")
+  #   Tynn.plugin(Tynn::Session, secret: "__change_me_not_secure__")
   #
   #   Tynn.define do
-  #     root do
-  #       res.write(sprintf("hei %s", session[:username]))
-  #     end
+  #     on("login") do
+  #       post do
+  #         # ...
+  #
+  #         session[:user_id] = user.id
   #
-  #     on(:username) do |username|
-  #       session[:username] = username
+  #         res.redirect("/admin")
+  #       end
   #     end
   #   end
   #
@@ -28,27 +30,27 @@ class Tynn
   # attacker to tamper the data. So, it's recommended to load the token
   # from the environment.
   #
-  # Examples
-  #
   #   Tynn.plugin(Tynn::Session, secret: ENV["SESSION_SECRET"])
   #
-  # Under the hood, Tynn::Session uses the +Rack::Session::Cookie+ middleware.
-  # Thus, supports all the options available for this middleware:
+  # Under the hood, Tynn::Session uses the <tt>Rack::Session::Cookie</tt>
+  # middleware. Thus, supports all the options available for this middleware:
   #
-  # key          - The name of the cookie. Defaults to <tt>"rack.session"</tt>.
+  # [key]
+  #   The name of the cookie. Defaults to <tt>"rack.session"</tt>.
   #
-  # httponly     - If +true+, sets the +HttpOnly+ flag. This mitigates the
-  #                risk of client side scripting accessing the cookie. Defaults
-  #                to +true+.
+  # [httponly]
+  #   If <tt>true</tt>, sets the <tt>HttpOnly</tt> flag. This mitigates the
+  #   risk of client side scripting accessing the cookie. Defaults to <tt>true</tt>.
   #
-  # secure       - If +true+, sets the +Secure+ flag. This tells the browser
-  #                to only transmit the cookie over HTTPS. Defaults to `false`.
+  # [secure]
+  #   If <tt>true</tt>, sets the <tt>Secure</tt> flag. This tells the browser
+  #   to only transmit the cookie over HTTPS. Defaults to <tt>false</tt>.
   #
-  # expire_after - The lifespan of the cookie. If +nil+, the session cookie
-  #                is temporary and is no retained after the browser is
-  #                closed. Defaults to +nil+.
+  # [expire_after]
+  #   The lifespan of the cookie. If <tt>nil</tt>, the session cookie is temporary
+  #   and is no retained after the browser is closed. Defaults to <tt>nil</tt>.
   #
-  # Examples
+  # <tt></tt>
   #
   #   Tynn.plugin(
   #     Tynn::Session,
@@ -60,27 +62,59 @@ class Tynn
   #   )
   #
   module Session
-    # Internal: Configures Rack::Session::Cookie middleware.
-    def self.setup(app, options = {})
-      if app.settings[:ssl]
-        options = { secure: true }.merge(options)
+    SECRET_MIN_LENGTH = 30 # :nodoc:
+
+    def self.setup(app, options = {}) # :nodoc:
+      secret = options[:secret]
+
+      if secret.nil?
+        raise <<~MSG
+          No secret option provided to Tynn::Session.
+
+          Tynn::Session uses a secret token to sign the cookie data, thus
+          unauthorized means can't alter it. Please, add the secret option
+          to your code:
+
+              #{ app }.plugin(Tynn::Session, secret: "__a_long_random_secret__", ...)
+
+          If you're sharing your code publicly, make sure the secret key
+          is kept private. Knowing the secret allows an attacker to tamper
+          the data. You can use environment variables to store the secret:
+
+              #{ app }.plugin(Tynn::Session, secret: ENV.fetch("SESSION_SECRET"), ...)
+        MSG
+      end
+
+      if secret.length < SECRET_MIN_LENGTH
+        raise <<~MSG
+          The secret provided is shorter than the minimum length.
+
+          Make sure the secret is long and all random. You can generate a
+          secure secret key with:
+
+              $ ruby -r securerandom -e "puts SecureRandom.hex(64)"
+        MSG
       end
 
-      app.use(Rack::Session::Cookie, options)
+      app.use(Rack::Session::Cookie, {
+        coder: Rack::Session::Cookie::Base64::JSON.new,
+        hmac: OpenSSL::Digest::SHA256,
+        same_site: :Lax
+      }.merge(options))
     end
 
     module InstanceMethods
-      # Public: Returns the session hash.
-      #
-      # Examples
+      # Returns the session hash.
       #
-      #   session # => {}
+      #   session
+      #   # => {}
       #
       #   session[:foo] = "foo"
-      #   session[:foo] # => "foo"
+      #   session[:foo]
+      #   # => "foo"
       #
       def session
-        return req.session
+        req.session
       end
     end
   end

data/lib/tynn/settings.rb

@@ -1,8 +1,7 @@
+# frozen_string_literal: true
+
 class Tynn
-  # Public: It provides a settings API for applications. This plugin is
-  # included by default.
-  #
-  # Examples
+  # It provides a settings API for applications and plugins.
   #
   #   require "tynn"
   #
@@ -13,7 +12,7 @@ class Tynn
   #
   #     module ClassMethods
   #       def app_name
-  #         return settings[:app_name]
+  #         settings[:app_name]
   #       end
   #     end
   #   end
@@ -23,55 +22,85 @@ class Tynn
   #   Tynn.app_name
   #   # => "MyApp"
   #
+  #   Tynn.set(:app_name, "MyAwesomeApp")
+  #
+  #   Tynn.app_name
+  #   # => "MyAwesomeApp"
+  #
+  # # This plugin is included by default.
+  #
   module Settings
-    # Internal: Returns a deep copy of a Hash.
-    def self.deepclone(hash)
+    def self.deepclone(hash) # :nodoc:
       default_proc, hash.default_proc = hash.default_proc, nil
 
-      return Marshal.load(Marshal.dump(hash))
+      Marshal.load(Marshal.dump(hash))
     ensure
       hash.default_proc = default_proc
     end
 
     module ClassMethods
-      # Internal: Copies settings into the subclass.
-      # If a setting is not found, checks parent's settings.
-      def inherited(subclass)
+      # Copies settings into the subclass. If a setting is not found,
+      # checks parent's settings.
+      def inherited(subclass) # :nodoc:
         subclass.settings.replace(Tynn::Settings.deepclone(settings))
         subclass.settings.default_proc = proc { |h, k| h[k] = settings[k] }
       end
 
       # Returns a Hash with the application settings.
       #
-      # Examples
-      #
       #   Tynn.set(:environment, :development)
       #
       #   Tynn.settings
       #   # => { :environment => :development }
       #
       def settings
-        return @settings ||= {}
+        @settings ||= {}
       end
-    end
 
-    module InstanceMethods
-      # Returns a Hash with the application settings.
+      # Sets an <tt>option</tt> to the given </tt>value</tt>. If a setting
+      # with the <tt>option</tt> key exists and is a hash value, it merges
+      # the stored hash with <tt>value</tt>.
       #
-      # Examples
+      #   Tynn.set(:environment, :staging)
       #
-      #   Tynn.set(:environment, :development)
+      #   Tynn.settings[:environment]
+      #   # => :staging
       #
-      #   Tynn.define do
-      #     get do
-      #       res.write(settings[:environment])
-      #     end
-      #   end
+      #   Tynn.default_headers
+      #   # => { "Content-Type" => "text/html" }
       #
-      #   GET / # => 200 "development"
+      #   Tynn.set(:default_headers, "X-Frame-Options" => "DENY")
       #
-      def settings
-        return self.class.settings
+      #   Tynn.default_headers
+      #   # => { "Content-Type" => "text/html", "X-Frame-Options" => "DENY" }
+      #
+      def set(option, value)
+        v = settings[option]
+
+        if Hash === v
+          set!(option, v.merge(value))
+        else
+          set!(option, value)
+        end
+      end
+
+      # Sets an <tt>option</tt> to the given </tt>value</tt>.
+      #
+      #   Tynn.set!(:environment, :staging)
+      #
+      #   Tynn.settings[:environment]
+      #   # => :staging
+      #
+      #   Tynn.default_headers
+      #   # => { "Content-Type" => "text/html" }
+      #
+      #   Tynn.set!(:default_headers, "X-Frame-Options" => "DENY")
+      #
+      #   Tynn.default_headers
+      #   # => { "X-Frame-Options" => "DENY" }
+      #
+      def set!(option, value)
+        settings[option] = value
       end
     end
   end

data/lib/tynn/ssl.rb

@@ -1,14 +1,37 @@
+# frozen_string_literal: true
+
 class Tynn
-  # Public: Enforces secure HTTP requests by:
+  # Enforces secure HTTP requests by:
   #
   # 1. Redirecting HTTP requests to their HTTPS counterparts.
   #
-  # 2. Setting the +Strict-Transport-Security+ header. This ensures the
-  #    browser never visits the http version of a website. This reduces
-  #    the impact of leaking session data through cookies and external
-  #    links, and defends against Man-in-the-middle attacks.
+  # 2. Setting the HTTP <tt>Strict-Transport-Security</tt> header (HSTS).
+  #    This ensures the browser never visits the http version of a website.
+  #    This reduces the impact of leaking session data through cookies
+  #    and external links, and defends against Man-in-the-middle attacks.
+  #
+  # 3. Setting the <tt>secure</tt> flag on cookies. This tells the browser to
+  #    only transmit them over HTTPS.
+  #
+  # You can configure HSTS passing a <tt>:hsts</tt> option. The following options
+  # are supported:
+  #
+  # - *:expires* - The time, in seconds, that the browser access the site only
+  #   by HTTPS. Defaults to 180 days.
   #
-  # Examples
+  # - *:subdomains* - If this is <tt>true</tt>, the rule applies to all the
+  #   site's subdomains as well. Defaults to <tt>true</tt>.
+  #
+  # - *:preload* - A limitation of HSTS is that the initial request remains
+  #   unprotected if it uses HTTP. The same applies to the first request after
+  #   the activity period specified by <tt>max-age</tt>. Modern browsers implements
+  #   a "HSTS preload list", which contains known sites supporting HSTS. If you
+  #   would like to include your website into the list, set this option to
+  #   <tt>true</tt> and submit your domain to this form[https://hstspreload.appspot.com/].
+  #   Supported by Chrome, Firefox, IE11+ and IE Edge.
+  #
+  # To disable HSTS, you will need to tell the browser to expire it immediately.
+  # Setting <tt>hsts: false</tt> is a shortcut for <tt>hsts: { expires: 0 }</tt>.
   #
   #   require "tynn"
   #   require "tynn/ssl"
@@ -21,95 +44,80 @@ class Tynn
   #   app = Tynn::Test.new
   #   app.get("/", {}, "HTTP_HOST" => "tynn.xyz")
   #
-  #   app.res.headers["Location"]
-  #   # => "https://tynn.xyz/"
-  #
-  # You can configure HSTS with <tt>{ hsts: { ... } }</tt>. It supports the
-  # following options:
-  #
-  # expires    - The time, in seconds, that the browser access the site only
-  #              by HTTPS. Defaults to 180 days.
-  # subdomains - If this is +true+, the rule applies to all the site's
-  #              subdomains as well. Defaults to +true+.
-  # preload    - A limitation of HSTS is that the initial request remains
-  #              unprotected if it uses HTTP. The same applies to the first
-  #              request after the activity period specified by +max-age+.
-  #              Modern browsers implements a "STS preloaded list", which
-  #              contains known sites supporting HSTS. If you would like to
-  #              include your website into the list, set this options to +true+
-  #              and submit your domain to this {form}[https://hstspreload.appspot.com/].
-  #              Supported by Chrome, Firefox, IE11+ and IE Edge.
-  #
-  # Examples
+  #   app.res.status   # => 301
+  #   app.res.location # => "https://tynn.xyz/"
   #
+  #   # Using different HSTS options
   #   Tynn.plugin(
   #     Tynn::SSL,
   #     hsts: {
   #       expires: 31_536_000,
-  #       includeSubdomains: true,
+  #       includeSubdomains: false,
   #       preload: true
   #     }
   #   )
   #
-  #   app = Tynn::Test.new
-  #   app.get("/", {}, "HTTPS" => "on")
-  #
-  #   app.res.headers["Strict-Transport-Security"]
-  #   # => "max-age=31536000; includeSubdomains; preload"
-  #
-  # To disable HSTS, you will need to tell the browser to expire it
-  # immediately.
-  #
-  # Examples
-  #
-  #   Tynn.plugin(Tynn::SSL, hsts: { expires: 0 })
+  #   # Disabling HSTS
+  #   Tynn.plugin(Tynn::SSL, hsts: false)
   #
-  class SSL
+  module SSL
     def self.setup(app, hsts: {}) # :nodoc:
-      app.use(self, hsts: hsts)
+      app.use(Tynn::SSL::Middleware, hsts: hsts)
     end
 
-    def initialize(app, hsts: {}) # :nodoc:
-      @app = app
-      @hsts_header = build_hsts_header(hsts)
-    end
+    class Middleware # :nodoc:
+      HSTS_MAX_AGE = 15_552_000 # 180 days
+
+      def initialize(app, hsts: {})
+        @app = app
+        @hsts_header = build_hsts_header(hsts || { expires: 0 })
+      end
 
-    def call(env) # :nodoc:
-      request = Rack::Request.new(env)
+      def call(env)
+        request = Rack::Request.new(env)
 
-      if request.ssl?
-        response = @app.call(env)
+        return redirect_to_https(request) unless request.ssl?
 
-        set_hsts_header!(response[1])
+        @app.call(env).tap do |_, headers, _|
+          set_hsts_header!(headers)
 
-        return response
-      else
-        return [301, redirect_headers(request), []]
+          flag_cookies_as_secure!(headers)
+        end
       end
-    end
 
-    private
+      private
 
-    def build_hsts_header(options)
-      header = sprintf("max-age=%i", options.fetch(:expires, 15_552_000))
-      header << "; includeSubdomains" if options.fetch(:subdomains, true)
-      header << "; preload" if options[:preload]
+      def build_hsts_header(options)
+        header = sprintf("max-age=%i", options.fetch(:expires, HSTS_MAX_AGE))
+        header << "; includeSubdomains" if options.fetch(:subdomains, true)
+        header << "; preload" if options[:preload]
 
-      return header
-    end
+        header
+      end
 
-    def set_hsts_header!(headers)
-      headers["Strict-Transport-Security".freeze] ||= @hsts_header
-    end
+      def redirect_to_https(request)
+        host = request.host
+        port = request.port
 
-    def redirect_headers(request)
-      return { "Location" => https_location(request) }
-    end
+        location = "https://" + host
+        location << ":#{ port }" if port != 80 && port != 443
+        location << request.fullpath
+
+        [301, { "Location" => location }, []]
+      end
 
-    HTTPS_LOCATION = "https://%s%s".freeze
+      def set_hsts_header!(headers)
+        headers["Strict-Transport-Security"] ||= @hsts_header
+      end
+
+      def flag_cookies_as_secure!(headers)
+        return unless cookies = headers["Set-Cookie"]
 
-    def https_location(request)
-      return sprintf(HTTPS_LOCATION, request.host, request.fullpath)
+        headers["Set-Cookie"] = cookies.split("\n").map do |cookie|
+          cookie << "; secure" if cookie !~ /;\s*secure\s*(;|$)/i
+          cookie
+        end.join("\n")
+      end
     end
   end
 end