kindergarten 0.0.5

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec/support/db/test.db
+spec/support/log/test.log

data/.rspec

@@ -0,0 +1 @@
+--color -f d

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+  - ruby-head
+  - jruby-head
+  - 1.8.7
+  - ree

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kindergarten.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Hartog C. de Mik
+
+MIT License
+
+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,89 @@
+# Kindergarten
+
+[![Build Status](https://secure.travis-ci.org/coffeeaddict/kindergarten.png)](http://travis-ci.org/coffeeaddict/kindergarten)
+
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/coffeeaddict/kindergarten)
+
+A way to achieve modularity and modular security with a sandbox on steroids.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'kindergarten'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kindergarten
+
+## Usage
+
+```ruby
+# define a child
+child = User.find(2)
+
+# define a module (perimeter) for the child to play in
+class MyPlayModule < Kindergarten::Perimeter
+  # use can-can rules to govern the perimeter
+  govern do |child|
+    can :watch, Television
+    cannot :watch, CableTV
+
+    can :eat, Candy do |candy|
+      child.quotum.allows(candy)
+    end
+  end
+
+  # define methods for the sandbox
+  sandbox :watch_tv, :eat
+
+  def watch_tv(tv)
+    guard(:watch, tv)
+    child.watch(tv)
+
+    sleep(:four)
+  end
+
+  def eat(candy)
+    guard(:eat, candy)
+    child.eat(candy)
+  end
+
+  def sleep(len) # not_accessible_from_outside
+    child.sleep(len)
+  end
+end
+
+# load the child and the module into a sandbox
+sandbox = Kindergarten.sandbox(child)
+sandbox.load_module(MyPlayPerimeter)
+
+# you can now call the sandboxed methods on the sandbox
+sandbox.watch_tv(CableTV.new)  # fails with Kindergarten::AccessDenied
+30.times do
+  sandbox.eat(Liquorice.new)   # fails after a while
+end
+
+sandbox.sleep(:long)           # fails with NoMethodError
+
+sandbox.allowed?(:watch, Television)
+# => true
+```
+
+You are not restricted to only one perimeter/module - that would be most
+boring...
+
+Infact, the above is the essence of things - but there is much much more fun
+hidden inside the Kindergarten. More will follow on the Wiki
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/TODO.md

@@ -0,0 +1,6 @@
+# Kindergarten TODO
+
+## Travis
+
+* Change specs to use ruby-1.8 hashes so Travis can run 1.8.x
+* Switch to mysql for testing jrubies 

data/kindergarten.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/kindergarten/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Hartog C. de Mik"]
+  gem.email         = ["hartog@organisedminds.com"]
+  gem.description   = %q{A kindergarten with a perimeter, a governess and a sandbox}
+  gem.summary       = %q{Provide a kindergarten for your code to play in}
+  gem.homepage      = ""
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "kindergarten"
+  gem.require_paths = ["lib"]
+  gem.version       = Kindergarten::VERSION
+
+  gem.add_dependency('cancan', ['~> 1.6.8'])
+  gem.add_dependency('activesupport', ['~> 3.2'])
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('rspec', ['~> 2.10'])
+  gem.add_development_dependency('activerecord', ['~> 3.2'])
+  gem.add_development_dependency('sqlite3')
+end

data/lib/kindergarten.rb

@@ -0,0 +1,17 @@
+require 'cancan'
+require 'active_support/core_ext'
+
+require "kindergarten/version"
+require "kindergarten/sandbox"
+require "kindergarten/exceptions"
+require "kindergarten/governesses"
+require "kindergarten/perimeter"
+
+module Kindergarten
+  class << self
+    def sandbox(child)
+      Kindergarten::Sandbox.new(child)
+    end
+  end
+end
+

data/lib/kindergarten/exceptions.rb

@@ -0,0 +1,19 @@
+module Kindergarten
+  # Signals unallowed access
+  class AccessDenied < CanCan::AccessDenied
+    def initialize(action, target, opts)
+      message = opts.delete(:message)
+      if message.blank?
+        name    = target.is_a?(Class) ? target.name : target.class.name
+        message = "You are not allowed to #{action} that #{name.downcase}"
+      end
+
+      super(message, action, target)
+    end
+  end
+
+  class Perimeter
+    # Signals bad sandbox method implementation  
+    class Unguarded < SecurityError; end
+  end
+end

data/lib/kindergarten/governesses.rb

@@ -0,0 +1,19 @@
+module Kindergarten
+  # Hash with only allowed keys
+  class ScrubbedHash < Hash; end
+
+  # Hash with only allowed keys and untainted values
+  class RinsedHash < Hash; end
+
+  module Governesses
+    class << self
+      attr_accessor :forbidden_keys
+    end
+
+    self.forbidden_keys = []
+  end
+end
+
+require "kindergarten/governesses/head_governess"
+require "kindergarten/governesses/strict_governess"
+require "kindergarten/governesses/easy_governess"

data/lib/kindergarten/governesses/easy_governess.rb

@@ -0,0 +1,11 @@
+module Kindergarten
+  # A very easy governess, lets everything happen unguarded. Perhaps not such
+  # a good idea to be using this...
+  #
+  class EasyGoverness < HeadGoverness
+    def initialize(child)
+      super
+      @unguarded = true
+    end
+  end
+end

data/lib/kindergarten/governesses/head_governess.rb

@@ -0,0 +1,144 @@
+module Kindergarten
+  # The Governess keeps an eye on the child in the sandbox and makes sure
+  # she plays nicely and within the bounds of legality
+  #
+  class HeadGoverness
+    include CanCan::Ability
+
+    def initialize(child)
+      @child     = child
+      @unguarded = false
+      @rules     = []
+    end
+
+    # The governess is empty when no rules have been defined
+    def empty?
+      @rules.empty?
+    end
+
+    # Perform a sandbox method within the care of the governess.
+    #
+    # The HeadGoverness does nothing with it.
+    #
+    # @param [Symbol] method The name of the method that will be executed (for
+    #   logging, record-keeping, raising, etc.)
+    # @return The result of the block
+    #
+    def governed(method, &block)
+      raise "You must specify a block" unless block_given?
+
+      return yield
+    end
+
+    # Check to see if the child can do something, increments @guard_count
+    #
+    # @param action Action to take
+    # @param target On given target
+    # @param opts [Hash] options
+    # @option opts [String] :message The message on access denied
+    #
+    # @raise [Kindergarten::AccessDenied] when the kindergarten is guarded and
+    #   the action is not allowed
+    #
+    # @return The given target to allow
+    #     def project(id)
+    #       project = Project.find(id)
+    #       guard(:view, project)
+    #     end
+    #
+    def guard(action, target, opts={})
+      if guarded? && cannot?(action, target)
+        raise Kindergarten::AccessDenied.new(action, target, opts)
+      end
+
+      # to allow
+      #   def project(id)
+      #     project = Project.find(id)
+      #     guard(:view, project)
+      #   end
+      #
+      return target
+    end
+
+    # When a block is given, set the Governess to unguarded during the
+    # execution of the block
+    #
+    def unguarded(&block)
+      if block_given?
+        before = @unguarded
+
+        @unguarded = true
+        yield
+        @unguarded = before
+      end
+    end
+
+    def guarded?
+      !unguarded?
+    end
+
+    def unguarded?
+      !!@unguarded
+    end
+
+    # Scrub a hash of any key that is not specified
+    #
+    # @param [Hash] attributes An attributes-hash to scrub
+    # @param [Symbol] list A list of allowed attributes
+    #
+    # @return [ScrubbedHash] a hash with only allowed keys
+    def scrub(attributes, *list)
+      list.map!(&:to_sym)
+
+      forbidden = Kindergarten::Governesses.forbidden_keys
+
+      Kindergarten::ScrubbedHash[
+        attributes.symbolize_keys!.delete_if do |key,value|
+          forbidden.include?(key) || !list.include?(key)
+        end
+      ]
+    end
+
+    # Scrub a hash of any key that is not specified
+    #
+    # @param [Hash] attributes An attributes-hash to scrub
+    # @param [Hash] untaint_opts Specify a Regexp for each key. The value from
+    #   the attributes will be matched against the regexp and replaced with
+    #   the first result.
+    #
+    #   specify :pass instead of a Regexp to let the value pass without
+    #   matching (usefull for non strings, etc.)
+    #
+    # @return [RinsedHash] a hash with only allowed keys and untainted values
+    #
+    # @example Untaint
+    #   rinse(attributes, :name => /^([a-Z0-9]+)/, :description => /([\w\s-]+)/mg)
+    #
+    # @example Pass on a Date attribute
+    #   rinse(attributes, :name => /([\w\s-]+)/, :date => :pass)
+    #
+    # @example Bad practice
+    #   # beware of the dot-star!
+    #   rinse(attributes, :name => /(.*)/)
+    #
+    def rinse(attributes, untaint_opts)
+      untaint_opts.symbolize_keys!
+
+      scrubbed = scrub(attributes, *untaint_opts.keys)
+
+      scrubbed.each do |key, value|
+        untaint = untaint_opts[key]
+        next if untaint == :pass
+
+        match = value.match(untaint)
+        if match.nil?
+          scrubbed.delete key
+        else
+          scrubbed[key] = match[1]
+        end
+      end
+
+      return Kindergarten::RinsedHash[scrubbed]
+    end
+  end
+end

data/lib/kindergarten/governesses/strict_governess.rb

@@ -0,0 +1,48 @@
+module Kindergarten
+  # A very strict governess, forces all the sandbox methods to use the guard
+  # methods.
+  #
+  # @note
+  #   Does not specify how to rollback when the guard method was not called,
+  #   You're on your own there...
+  #
+  class StrictGoverness < HeadGoverness
+    # Check how often the perimeter guarded something
+    attr_reader :guard_count
+
+    def initialize(child)
+      super
+      @guard_count = 0
+    end
+
+    # Force the use of guard inside sandbox methods
+    #
+    # @raise Kindergarten::Perimeter::Unguarded when the guard count did not
+    #   increment during the block execution
+    #
+    def governed(method, &block)
+      before = self.guard_count
+      res    = yield
+
+      if @unguarded != true && self.guard_count == before
+        raise Kindergarten::Perimeter::Unguarded.new(
+          "#{method} was executed without propper guarding"
+        )
+      end
+
+      return res
+    end
+
+    # guard something and increment the guard count
+    def guard(*args)
+      @guard_count += 1
+      super
+    end
+
+    # allow something unguarded and increment the guard count
+    def unguarded(&block)
+      @guard_count += 1
+      super
+    end
+  end
+end