cleanroom 1.0.0

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+[:unit, :functional].each do |type|
+  RSpec::Core::RakeTask.new(type) do |t|
+    t.pattern = "spec/#{type}/**/*_spec.rb"
+    t.rspec_opts = [].tap do |a|
+      a.push('--color')
+      a.push('--format progress')
+    end.join(' ')
+  end
+end
+
+namespace :travis do
+  desc 'Run tests on Travis'
+  task ci: %w(unit functional)
+end
+
+task default: %w(travis:ci)

data/cleanroom.gemspec

@@ -0,0 +1,37 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cleanroom'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'cleanroom'
+  spec.version       = Cleanroom::VERSION
+  spec.author        = 'Seth Vargo'
+  spec.email         = 'sethvargo@gmail.com'
+  spec.summary       = '(More) safely evaluate Ruby DSLs with cleanroom'
+  spec.description   = <<-EOH.gsub(/^ {4}/, '').gsub(/\r?\n/, ' ').strip
+    Ruby is an excellent programming language for creating and managing custom
+    DSLs, but how can you securely evaluate a DSL while explicitly controlling
+    the methods exposed to the user? Our good friends instance_eval and
+    instance_exec are great, but they expose all methods - public, protected,
+    and private - to the user. Even worse, they expose the ability to
+    accidentally or intentionally alter the behavior of the system! The
+    cleanroom pattern is a safer, more convenient, Ruby-like approach for
+    limiting the information exposed by a DSL while giving users the ability to
+    write awesome code!
+  EOH
+  spec.homepage      = 'https://github.com/sethvargo/cleanroom'
+  spec.license       = 'Apache 2.0'
+
+  spec.required_ruby_version = '>= 1.9.3'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.0'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+end

data/lib/cleanroom.rb

@@ -0,0 +1,188 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative 'cleanroom/errors'
+require_relative 'cleanroom/version'
+
+module Cleanroom
+  #
+  # Callback for when this module is included.
+  #
+  # @param [Class] base
+  #
+  def self.included(base)
+    base.send(:extend,  ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  #
+  # Callback for when this module is included.
+  #
+  # @param [Class] base
+  #
+  def self.extended(base)
+    base.send(:extend,  ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  #
+  # Class methods
+  #
+  module ClassMethods
+    #
+    # Evaluate the file in the context of the cleanroom.
+    #
+    # @param [Class] instance
+    #   the instance of the class to evaluate against
+    # @param [String] filepath
+    #   the path of the file to evaluate
+    #
+    def evaluate_file(instance, filepath)
+      absolute_path = File.expand_path(filepath)
+      file_contents = IO.read(absolute_path)
+      evaluate(instance, file_contents, absolute_path, 1)
+    end
+
+    #
+    # Evaluate the string or block in the context of the cleanroom.
+    #
+    # @param [Class] instance
+    #   the instance of the class to evaluate against
+    # @param [Array<String>] args
+    #   the args to +instance_eval+
+    # @param [Proc] block
+    #   the block to +instance_eval+
+    #
+    def evaluate(instance, *args, &block)
+      cleanroom.new(instance).instance_eval(*args, &block)
+    end
+
+    #
+    # Expose the given method to the DSL.
+    #
+    # @param [Symbol] name
+    #
+    def expose(name)
+      unless public_method_defined?(name)
+        raise NameError, "undefined method `#{name}' for class `#{self.name}'"
+      end
+
+      exposed_methods[name] = true
+    end
+
+    #
+    # The list of exposed methods.
+    #
+    # @return [Hash]
+    #
+    def exposed_methods
+      @exposed_methods ||= from_superclass(:exposed_methods, {}).dup
+    end
+
+    private
+
+    #
+    # The cleanroom instance for this class. This method is intentionally
+    # NOT cached!
+    #
+    # @return [Class]
+    #
+    def cleanroom
+      exposed = exposed_methods.keys
+      parent = self.name || 'Anonymous'
+
+      Class.new(Object) do
+        class << self
+          def class_eval
+            raise Cleanroom::InaccessibleError.new(:class_eval, self)
+          end
+
+          def instance_eval
+            raise Cleanroom::InaccessibleError.new(:instance_eval, self)
+          end
+        end
+
+        define_method(:initialize) do |instance|
+          define_singleton_method(:__instance__) do
+            unless caller[0].include?(__FILE__)
+              raise Cleanroom::InaccessibleError.new(:__instance__, self)
+            end
+
+            instance
+          end
+        end
+
+        exposed.each do |exposed_method|
+          define_method(exposed_method) do |*args, &block|
+            __instance__.public_send(exposed_method, *args, &block)
+          end
+        end
+
+        define_method(:class_eval) do
+          raise Cleanroom::InaccessibleError.new(:class_eval, self)
+        end
+
+        define_method(:inspect) do
+          "#<#{parent} (Cleanroom)>"
+        end
+        alias_method :to_s, :inspect
+      end
+    end
+
+    #
+    # Get the value from the superclass, if it responds, otherwise return
+    # +default+. Since class instance variables are **not** inherited upon
+    # subclassing, this is a required check to ensure subclasses inherit
+    # exposed DSL methods.
+    #
+    # @param [Symbol] m
+    #   the name of the method to find
+    # @param [Object] default
+    #   the default value to return if not found
+    #
+    def from_superclass(m, default = nil)
+      return default if superclass == Cleanroom
+      superclass.respond_to?(m) ? superclass.send(m) : default
+    end
+  end
+
+  #
+  # Instance Mehtods
+  #
+  module InstanceMethods
+    #
+    # Evaluate the file against the current instance.
+    #
+    # @param (see Cleanroom.evaluate_file)
+    # @return [self]
+    #
+    def evaluate_file(filepath)
+      self.class.evaluate_file(self, filepath)
+      self
+    end
+
+    #
+    # Evaluate the contents against the current instance.
+    #
+    # @param (see Cleanroom.evaluate_file)
+    # @return [self]
+    #
+    def evaluate(*args, &block)
+      self.class.evaluate(self, *args, &block)
+      self
+    end
+  end
+end

data/lib/cleanroom/errors.rb

@@ -0,0 +1,33 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Cleanroom
+  class Error < StandardError; end
+
+  class InaccessibleError < Error
+    def initialize(name, instance)
+      @name, @instance = name, instance
+    end
+
+    def to_s
+<<-EOH.gsub(/\r?\n/, ' ')
+Undefined local variable or method `#{@name}' for #{@instance}. It may have
+been removed for the purposes of evaluating the DSL or for added security. If
+you feel you have reached this message in error, please open an issue.
+EOH
+    end
+  end
+end

data/lib/cleanroom/rspec.rb

@@ -0,0 +1,60 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative '../cleanroom'
+
+unless defined?(RSpec)
+  require 'rspec'
+end
+
+#
+# Assert a given method is exposed on a class.
+#
+# @example Checking against an instance
+#   expect(:method_1).to be_an_exposed_method_on(instance)
+#
+# @example Checking against a class
+#   expect(:method_1).to be_an_exposed_method_on(klass)
+#
+RSpec::Matchers.define :be_an_exposed_method_on do |object|
+  match do |name|
+    if object.is_a?(Class)
+      object.exposed_methods.key?(name.to_sym)
+    else
+      object.class.exposed_methods.key?(name.to_sym)
+    end
+  end
+end
+
+#
+# Assert a given class or instance has an exposed method.
+#
+# @example Checking against an instance
+#   expect(instance).to have_exposed_method(:method_1)
+#
+# @example Checking against a class
+#   expect(klass).to have_exposed_method(:method_1)
+#
+RSpec::Matchers.define :have_exposed_method do |name|
+  match do |object|
+    if object.is_a?(Class)
+      object.exposed_methods.key?(name.to_sym)
+    else
+      object.class.exposed_methods.key?(name.to_sym)
+    end
+  end
+end
+

data/lib/cleanroom/version.rb

@@ -0,0 +1,24 @@
+#
+# Copyright 2014 Seth Vargo <sethvargo@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Cleanroom
+  #
+  # The version of the Cleanroom gem.
+  #
+  # @return [String]
+  #
+  VERSION = '1.0.0'
+end

data/spec/functional/cleanroom_spec.rb

@@ -0,0 +1,96 @@
+require 'spec_helper'
+
+describe Cleanroom do
+  let(:klass) do
+    Class.new do
+      NULL = Object.new.freeze unless defined?(NULL)
+
+      include Cleanroom
+
+      def method_1(val = NULL)
+        if val.equal?(NULL)
+          @method_1
+        else
+          @method_1 = val
+        end
+      end
+      expose :method_1
+
+      def method_2(val = NULL)
+        if val.equal?(NULL)
+          @method_2
+        else
+          @method_2 = val
+        end
+      end
+      expose :method_2
+
+      def method_3
+        @method_3 = true
+      end
+    end
+  end
+
+  let(:instance) { klass.new }
+
+  describe '#evaluate_file' do
+    let(:path) { tmp_path('file.rb') }
+
+    before do
+      File.open(path, 'w') do |f|
+        f.write <<-EOH.gsub(/^ {10}/, '')
+          method_1 'hello'
+          method_2 false
+        EOH
+      end
+    end
+
+    it 'evaluates the file' do
+      instance.evaluate_file(path)
+      expect(instance.method_1).to eq('hello')
+      expect(instance.method_2).to be(false)
+    end
+  end
+
+  describe '#evaluate' do
+    let(:contents) do
+      <<-EOH.gsub(/^ {8}/, '')
+        method_1 'hello'
+        method_2 false
+      EOH
+    end
+
+    it 'evaluates the file' do
+      instance.evaluate(contents)
+      expect(instance.method_1).to eq('hello')
+      expect(instance.method_2).to be(false)
+    end
+  end
+
+  describe 'security' do
+    it 'restricts access to __instance__' do
+      expect {
+        instance.evaluate("__instance__")
+      }.to raise_error(Cleanroom::InaccessibleError)
+    end
+
+    it 'restricts access to __instance__ using :send' do
+      expect {
+        instance.evaluate("send(:__instance__)")
+      }.to raise_error(Cleanroom::InaccessibleError)
+    end
+
+    it 'restricts access to defining new methods' do
+      expect {
+        instance.evaluate <<-EOH.gsub(/^ {12}/, '')
+          self.class.class_eval do
+            def new_method
+              __instance__.method_3
+            end
+          end
+        EOH
+      }.to raise_error(Cleanroom::InaccessibleError)
+      expect(instance.instance_variables).to_not include(:@method_3)
+    end
+  end
+end