tainted_hash 0.0.1

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Rick Olson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# Tainted Hash
+
+A TaintedHash is a wrapper around a normal Hash that only exposes the keys that
+have been approved.  This is useful in cases where a Hash is built from user
+input from an external service (such as Rails or Sinatra).  By forcing the 
+developer to approve keys, no unexpected keys are passed to data stores.
+Because of this specific use case, it is assumed all keys are strings.
+
+By default, no keys have been approved.
+
+```ruby
+hash = {'a' => 1, 'b' => 2, 'c' => 3}
+tainted = TaintedHash.new hash
+```
+
+You can access keys manually to get the value and approve them:
+
+Use `#expose` to expose keys.
+
+```ruby
+tainted.include?(:a) # false
+tainted['a'] # Returns 1
+tainted[:a]  # Symbols are OK too.
+tainted.include?(:a) # false, not exposed
+tainted.expose :a
+tainted.include?(:a) # true
+tainted.keys # ['a']
+```
+
+If using Rails 2.3, require `tainted_hash/rails` to setup the necessary hooks.
+It amounts to little more than this:
+
+```ruby
+def wrap_params_with_tainted_hash
+  @_params = TaintedHash.new(@_params.to_hash)
+end
+```
+
+Set this up as a `before_filter` early in the stack.  However, it should run
+after filters like `#filter_parameter_logging` that needs to filter _any_
+key.
+
+## Note on Patches/Pull Requests
+1. Fork the project on GitHub.
+2. Make your feature addition or bug fix.
+3. Add tests for it. This is important so I don't break it in a future version
+   unintentionally.
+4. Commit, do not mess with rakefile, version, or history. (if you want to have
+   your own version, that is fine but bump version in a commit by itself I can
+   ignore when I pull)
+5. Send me a pull request. Bonus points for topic branches.
+

data/Rakefile

@@ -0,0 +1,134 @@
+#!/usr/bin/env rake
+
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{gem_file}"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    #exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/lib/tainted_hash/rails.rb

@@ -0,0 +1,14 @@
+require File.expand_path("../../tainted_hash", __FILE__)
+
+TaintedHash.send :include, TaintedHash::RailsMethods
+
+module TaintedHash::Controller
+  def wrap_params_with_tainted_hash
+    @_params = TaintedHash.new(@_params.to_hash)
+  end
+end
+
+if defined?(ActionController::Base)
+  ActionController::Base.send :include, TaintedHash::Controller
+end
+

data/lib/tainted_hash.rb

@@ -0,0 +1,238 @@
+require 'set'
+
+class TaintedHash < Hash
+  VERSION = "0.0.1"
+
+  class UnexposedError < StandardError
+    # Builds an exception when a TaintedHash has some unexposed keys.  Useful
+    # for testing and production notification of weird parameters.
+    def initialize(action, extras)
+      @action = action
+      @extras = extras
+      super("Extra params for #{@action} in tainted hash: #{@extras.inspect}")
+    end
+  end
+
+  def self.on_no_expose(&block)
+    @on_no_expose = block
+  end
+
+  def self.trigger_no_expose(hash)
+    @on_no_expose.call hash if @on_no_expose && (!block_given? || yield)
+  end
+
+  # Public: Gets the original hash that is being wrapped.
+  #
+  # Returns a Hash.
+  attr_reader :original_hash
+
+  # A Tainted Hash only exposes expected keys.  You can either expose them
+  # manually, or through common Hash methods like #values_at or #slice.  Once
+  # created, the internal Hash is frozen from future updates.
+  #
+  # hash      - Optional Hash used internally.
+  # new_class - Optional class used to create basic Hashes.  Default: Hash.
+  #
+  def initialize(hash = nil, new_class = nil)
+    (@original_hash = hash || {}).keys.each do |key|
+      key_s = key.to_s
+      next if key_s == key
+      @original_hash[key_s] = @original_hash.delete(key)
+    end
+
+    @new_class = new_class || Hash
+    @exposed_nothing = true
+  end
+
+  # Public: Exposes one or more keys for the hash.
+  #
+  # *keys - One or more String keys.
+  #
+  # Returns this TaintedHash.
+  def expose(*keys)
+    @exposed_nothing = false
+    keys.each do |key|
+      key_s = key.to_s
+      self[key_s] = @original_hash[key_s] if @original_hash.key?(key_s)
+    end
+    self
+  end
+
+  # Public: Exposes every key of the hash.
+  #
+  # Returns this TaintedHash.
+  def expose_all
+    @exposed_nothing = false
+    @original_hash.each do |key, value|
+      self[key] = value
+    end
+    self
+  end
+
+  # Public: Gets the unexposed keys from the original Hash.
+  #
+  # Returns an Array of String keys.
+  def extra_keys
+    @original_hash.keys - self.keys
+  end
+
+  # Public: Fetches the value in the hash at key, or a sensible default.
+  #
+  # key     - A String key to retrieve.
+  # default - A sensible default.
+  #
+  # Returns the value of the key, or the default.
+  def fetch(key, default = nil)
+    key_s = key.to_s
+    @original_hash.fetch key_s, default
+  end
+
+  # Public: Gets the value for the key, and exposes the key for the Hash.
+  #
+  # key - A String key to retrieve.
+  #
+  # Returns the value of at the key in Hash.
+  def [](key)
+    key_s = key.to_s
+    return if !@original_hash.key?(key_s)
+
+    case value = @original_hash[key_s]
+    when TaintedHash then value
+    when Hash
+      value = @original_hash[key_s] = self.class.new(value, @new_class)
+    else value
+    end
+  end
+
+  # Public: Attempts to set the key of a frozen hash.
+  #
+  # key   - String key to set.
+  # value - Value of the key.
+  #
+  # Returns nothing
+  def []=(key, value)
+    key_s = key.to_s
+    super(key_s, @original_hash[key_s] = case value
+      when TaintedHash then value
+      when Hash then self.class.new(value, @new_class)
+      else value
+      end)
+  end
+
+  # Public: Deletes the value from both the internal and current Hash.
+  #
+  # key - A String key to delete.
+  #
+  # Returns the value from the key.
+  def delete(key)
+    key_s = key.to_s
+    super(key_s)
+    @original_hash.delete key_s
+  end
+
+  # Public: Checks whether the given key has been exposed or not.
+  #
+  # key - A String key.
+  #
+  # Returns true if exposed, or false.
+  def include?(key)
+    super(key.to_s)
+  end
+
+  alias key? include?
+
+  # Public: Returns the values for the given keys, and exposes the keys.
+  #
+  # *keys - One or more String keys.
+  #
+  # Returns an Array of the values (or nil if there is no value) for the keys.
+  def values_at(*keys)
+    @original_hash.values_at *keys.map { |k| k.to_s }
+  end
+
+  # Public: Merges the given hash with the internal and a dup of the current
+  # Hash.
+  #
+  # hash - A Hash with String keys.
+  #
+  # Returns a dup of this TaintedHash.
+  def merge(hash)
+    dup.update(hash)
+  end
+
+  # Public: Updates the internal and current Hash with the given Hash.
+  #
+  # hash - A Hash with String keys.
+  #
+  # Returns this TaintedHash.
+  def update(hash)
+    hash.each do |key, value|
+      @original_hash[key.to_s] = value
+    end
+    self
+  end
+
+  alias merge! update
+
+  # Public: Enumerates through the exposed keys and valuesfor the hash.
+  #
+  # Yields the String key, and the value.
+  #
+  # Returns nothing.
+  def each
+    self.class.trigger_no_expose(self) { @exposed_nothing && size.zero? }
+    block = block_given? ? Proc.new : nil
+    super(&block)
+  end
+
+  # Public: Builds a normal Hash of the exposed values from this hash.
+  #
+  # Returns a Hash.
+  def to_hash
+    hash = @new_class.new
+    each do |key, value|
+      hash[key] = case value
+        when TaintedHash then value.to_hash
+        else value
+        end
+    end
+    hash
+  end
+
+  def inspect
+    %(#<#{self.class}:#{object_id} @hash=#{@original_hash.inspect} @exposed=#{keys.inspect}>)
+  end
+
+  module RailsMethods
+    def self.included(base)
+      base.send :alias_method, :stringify_keys!, :stringify_keys
+    end
+
+    # Public: Returns a portion of the Hash.
+    #
+    # *keys - One or more String keys.
+    #
+    # Returns a Hash of the requested keys and values.
+    def slice(*keys)
+      str_keys = @original_hash.keys & keys.map { |k| k.to_s }
+      hash = self.class.new
+      str_keys.each do |key|
+        hash[key] = @original_hash[key]
+      end
+      hash
+    end
+
+    def slice!(*keys)
+      raise NotImplementedError
+    end
+
+    def stringify_keys
+      self
+    end
+
+    def to_query
+      @original_hash.to_query
+    end
+  end
+end
+

data/tainted_hash.gemspec

@@ -0,0 +1,55 @@
+## This is the rakegem gemspec template. Make sure you read and understand
+## all of the comments. Some sections require modification, and others can
+## be deleted if you don't need them. Once you understand the contents of
+## this file, feel free to delete any comments that begin with two hash marks.
+## You can find comprehensive Gem::Specification documentation, at
+## http://docs.rubygems.org/read/chapter/20
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.3.5") if s.respond_to? :required_rubygems_version=
+
+  ## Leave these as is they will be modified for you by the rake gemspec task.
+  ## If your rubyforge_project name is different, then edit it and comment out
+  ## the sub! line in the Rakefile
+  s.name              = 'tainted_hash'
+  s.version           = '0.0.1'
+  s.date              = '2012-03-18'
+  s.rubyforge_project = 'tainted_hash'
+
+  ## Make sure your summary is short. The description may be as long
+  ## as you like.
+  s.summary     = "Hash wrapper."
+  s.description = "Hash wrapper."
+
+  ## List the primary authors. If there are a bunch of authors, it's probably
+  ## better to set the email to an email list or something. If you don't have
+  ## a custom homepage, consider using your GitHub URL or the like.
+  s.authors  = ["Rick Olson"]
+  s.email    = 'technoweenie@gmail.com'
+  s.homepage = 'https://github.com/technoweenie/tainted_hash'
+
+  ## This gets added to the $LOAD_PATH so that 'lib/NAME.rb' can be required as
+  ## require 'NAME.rb' or'/lib/NAME/file.rb' can be as require 'NAME/file.rb'
+  s.require_paths = %w[lib]
+
+  s.add_development_dependency 'test-unit'
+
+  ## Leave this section as-is. It will be automatically generated from the
+  ## contents of your Git repository via the gemspec task. DO NOT REMOVE
+  ## THE MANIFEST COMMENTS, they are used as delimiters by the task.
+  # = MANIFEST =
+  s.files = %w[
+    LICENSE.md
+    README.md
+    Rakefile
+    lib/tainted_hash.rb
+    lib/tainted_hash/rails.rb
+    tainted_hash.gemspec
+    test/tainted_hash_test.rb
+  ]
+  # = MANIFEST =
+
+  ## Test files will be grabbed from the file list. Make sure the path glob
+  ## matches what you actually use.
+  s.test_files = s.files.select { |path| path =~ %r{^test/*/.+\.rb} }
+end

data/test/tainted_hash_test.rb

@@ -0,0 +1,185 @@
+require File.expand_path("../../lib/tainted_hash", __FILE__)
+require 'test/unit'
+
+TaintedHash.send :include, TaintedHash::RailsMethods
+TaintedHash.on_no_expose do |hash|
+  raise
+end
+
+class TaintedHashTest < Test::Unit::TestCase
+  def setup
+    @hash = {'a' => 1, 'b' => 2, 'c' => {'name' => 'bob'}}
+    @tainted = TaintedHash.new @hash
+  end
+
+  def test_exposes_no_keys_by_default
+    assert !@tainted.include?('a')
+    assert !@tainted.include?('b')
+    assert_equal [], @tainted.keys
+
+    assert @hash.include?('a')
+    assert @hash.include?('b')
+    assert @hash.include?('c')
+  end
+
+  def test_dup
+    @tainted[:c].expose :name
+    @tainted.expose :a
+    dup = @tainted.dup.expose :b
+    assert_equal %w(a), @tainted.keys.sort
+    assert_equal %w(a b), dup.keys.sort
+  end
+
+  def test_expose_keys
+    assert !@tainted.include?(:a)
+    assert_equal [], @tainted.keys
+    @tainted.expose :a
+    assert @tainted.include?(:a)
+    assert_equal %w(a), @tainted.keys
+  end
+
+  def test_fetching_a_value
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:d)
+    assert_equal 1, @tainted.fetch(:a, :default)
+    assert_equal :default, @tainted.fetch(:d, :default)
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:d)
+  end
+
+  def test_getting_a_value
+    assert !@tainted.include?(:a)
+    assert_equal 1, @tainted[:a]
+    assert !@tainted.include?(:a)
+  end
+
+  def test_setting_a_value
+    assert !@tainted.include?(:a)
+    @tainted[:a] = 2
+    assert @tainted.include?(:a)
+    assert_equal 2, @tainted[:a]
+  end
+
+  def test_deleting_a_value
+    assert_equal 1, @tainted[:a]
+    assert !@tainted.include?(:a)
+    assert_equal 1, @tainted.delete(:a)
+    assert !@tainted.include?(:a)
+  end
+
+  def test_slicing_a_hash
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:b)
+    assert !@tainted.include?(:c)
+
+    output = @tainted.slice(:a, :b)
+    assert_equal({'a' => 1, 'b' => 2}, output.to_hash)
+
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:b)
+    assert !@tainted.include?(:c)
+
+    assert output.include?(:a)
+    assert output.include?(:b)
+    assert !output.include?(:c)
+  end
+
+  def test_yields_real_values
+    @tainted[:c].expose_all
+    @tainted.expose(:a).each do |key, value|
+      case key
+      when 'a' then assert_equal(1, value)
+      when 'c'
+        assert_equal({"name" => "bob"}, value)
+        assert_kind_of TaintedHash, value
+      end
+    end
+  end
+
+  def test_nested_hash_has_tainted_hashes
+    assert_kind_of TaintedHash, @tainted[:c]
+    assert_equal 'bob', @tainted[:c][:name]
+  end
+
+  def test_slicing_nested_hashes
+    slice = @tainted.slice :b, :c
+    assert_equal 2, slice[:b]
+    assert_equal 'bob', slice[:c][:name]
+    assert_equal %w(b c), slice.keys.sort
+    assert_equal [], slice[:c].keys
+  end
+
+  def test_slicing_and_building_hashes
+    hash = {'desc' => 'abc', 'files' => {'abc.txt' => 'abc'}}
+    tainted = TaintedHash.new hash
+
+    tainted.expose :desc, :files
+    assert tainted.include?(:desc)
+    assert tainted.include?(:files)
+
+    slice = tainted.slice :desc
+    assert slice.include?(:desc)
+    assert !slice.include?(:files)
+    assert_equal %w(desc), slice.keys
+    slice[:contents] = tainted[:files].expose_all
+    assert slice[:contents].include?('abc.txt')
+    assert_equal 'abc', slice[:contents]['abc.txt']
+  end
+
+  def test_update_hash
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:d)
+    @tainted.update :a => 2, :d => 1
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:d)
+    assert_equal 2, @tainted[:a]
+    assert_equal 1, @tainted[:d]
+  end
+
+  def test_does_not_expose_missing_keys
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:d)
+    @tainted.expose :a, :d
+    assert @tainted.include?(:a)
+    assert !@tainted.include?(:d)
+  end
+
+  def test_values_at_doesnt_expose_keys
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:b)
+    assert !@tainted.include?(:d)
+    assert_equal [1,2, nil], @tainted.values_at(:a, :b, :d)
+    assert !@tainted.include?(:a)
+    assert !@tainted.include?(:b)
+    assert !@tainted.include?(:d)
+  end
+
+  def test_requires_something_to_be_exposed
+    assert_raises RuntimeError do
+      @tainted.to_hash
+    end
+
+    @tainted.expose :missing
+    assert_equal({}, @tainted.to_hash)
+    @tainted.expose :a
+    assert_equal({'a' => 1}, @tainted.to_hash)
+  end
+
+  def test_works_with_integer_keys
+    hash = {'a' => 1, 1 => :a}
+    tainted = TaintedHash.new hash
+    assert_equal 1, tainted[:a]
+    assert_equal :a, tainted[1]
+  end
+
+  def test_gets_extra_keys
+    assert_equal %w(a b c), @tainted.extra_keys.sort
+    assert_equal %w(b c), @tainted.expose(:a).extra_keys.sort
+  end
+
+  def test_slice_doesnt_include_missing_keys
+    slice = @tainted.slice :a, :d
+    assert_equal({'a' => 1}, slice.to_hash)
+  end
+end
+

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: tainted_hash
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Rick Olson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-18 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Hash wrapper.
+email: technoweenie@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/tainted_hash.rb
+- lib/tainted_hash/rails.rb
+- tainted_hash.gemspec
+- test/tainted_hash_test.rb
+homepage: https://github.com/technoweenie/tainted_hash
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 17
+      segments: 
+      - 1
+      - 3
+      - 5
+      version: 1.3.5
+requirements: []
+
+rubyforge_project: tainted_hash
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 2
+summary: Hash wrapper.
+test_files: 
+- test/tainted_hash_test.rb