tenter 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cec3086122a566c922ffaeeda6e9d086c3dc78cd4900666e6e0ae2edefb15a3
-  data.tar.gz: 9dacc38cf020d66efa977acdbf2dfab90527b926445b5f7aa5e1e57206a7c0b0
+  metadata.gz: e691f0744f22ab97bd7793c42c570328202deffe78aae13965ca528b1376c2ae
+  data.tar.gz: 1d79b962a619c625d8b812951087d913a3739ff7d8ca0d4e20f4b101ad820059
 SHA512:
-  metadata.gz: b535883fe1cd070d1f8706a895c043db077950bb8e2c0d622e310e026831feed390a79980e5b0d39510c1abbed8f0f3b1072b8c4df0d92d390200724d2396193
-  data.tar.gz: 660effd30f91a6d47745ee803d73b5f0082183c49268aca2bf7fa3cabb52dfd03bef29d683c282d12081ce6c3362ca80a3e6e4b2be319184972f69b616344b0e
+  metadata.gz: 8e5516a38863c5885008b5752c86ecd7f5c6ba300b266b4867240c92dfdafb47804cd38ccd6215f2367ec747051bf6c4baca7775f3a8e9550713c5bc1943e587
+  data.tar.gz: 7180c0c1bd2a01091089230f81b506b9d931543bf66ca7708213c06b888ea8ebf6125fab512beef261276b5096e0fcd98c58b5f080bc5d889ce75af805f32f0f

data/lib/tenter.rb

@@ -5,7 +5,68 @@ require "tenter/hooks"
 require "tenter/utils"
 require "tenter/version"
 
+# A web app that provides webhooks for GitHub
+#
+# Tenter is a Sinatra-based web application that provides webhooks for use by
+# GitHub. It is intended to be used as a gem in a Rack app.
+#
+# At its simplest, a user could write a `config.ru` file consisting of:
+#
+#     require "tenter"
+#
+#     run Tenter::Hooks
+#
+# Tenter comes with a series of sane defaults. A version of Tenter that uses
+# these will expose endpoints in the form `/run/<action>/in/<dirname>/`. HTTP
+# POST requests sent to such an endpoint will, if authenticated, result in
+# Tenter executing the file on your the server's local file system at
+# `/<doc_root>/<dirname>/commands/<action>`.
+#
+# As astute readers will have observed, this is a potentially massive security
+# vulnerability. I am nevertheless able to sleep at night because Tenter
+# will only execute a file matching the action in a given directory if:
+#
+# 1. the POST request includes an `HTTP_X_HUB_SIGNATURE` header; and
+# 2. the value of this header matches the result of cryptographically
+#    signing the body of the HTTP request with a key defined by the user.
+#
+# By default, the key defined by the user is located in
+# `/<doc_root>/<dirname>/hooks.yaml`.
+#
+# A user can override the default settings for their instance of Tenter by
+# defining one or more of the following:
+#
+# - `:doc_root` (default: `"/var/www"`): The root directory in which each
+#   exposed directory will be located. It's recommended to specify this as an
+#   absolute path.
+#
+# - `:config_filename` (default: `"hooks.yaml"`): The filename of the
+#   configuration file in each exposed directory.
+#
+# - `:command_dir` (default: `"commands"`): The name of the subdirectory
+#   in which the files to execute are located.
+#
+# - `:log_file` (default `"log/commands.log"`): The path to the log file in each
+#   exposed directory where output from your commands will be logged. You can
+#   set this to `nil`to disable logging.
+#
+# The easiest way to do that is in the `config.ru` file:
+#
+#     require "tenter"
+#
+#     Tenter.settings = { log_file: nil } # disable logging
+#
+#     run Tenter::Hooks
+#
+# @since 0.1.1
+# @see https://github.com/pyrmont/tenter
 module Tenter
+
+  # Returns the default settings
+  #
+  # @return [Hash] the default settings
+  #
+  # @since 0.1.1
   def self.defaults
     { doc_root: "/var/www/",
       config_filename: "hooks.yaml",
@@ -14,15 +75,28 @@ module Tenter
       timestamp: true }
   end
 
+  # Resets Tenter's settings to their defaults
+  #
+  # @since 0.1.1
   def self.reset
     @settings = self.defaults
   end
 
+  # Updates the provided settings
+  #
+  # @param opts [Hash] the keys and values to update
+  #
+  # @since 0.1.1
   def self.settings=(opts = {})
     @settings = self.settings.merge opts
   end
 
+  # Returns the settings for this instance
+  #
+  # @return [Hash] the settings for this instance
+  #
+  # @since 0.1.1
   def self.settings
-    @settings ||= self.defaults 
+    @settings ||= self.defaults
   end
 end

data/lib/tenter/helpers.rb

@@ -3,14 +3,28 @@
 require "openssl"
 
 module Tenter
+
+  # Sinatra helpers for Tenter
+  #
+  # These helpers provide idiomatic methods for use in Sinatra routes. This
+  # module is intended to be called by passing it to the `Sinatra::Base.helpers`
+  # method.
+  #
+  # @since 0.1.1
+  # @api private
   module Helpers
+
+    # Authenticates the request
+    #
+    # @since 0.1.1
+    # @api private
     def authenticate
       msg = "X-Hub-Signature header not set"
       halt 400, msg unless request.env['HTTP_X_HUB_SIGNATURE']
 
       msg = "X-Hub-Signature header did not match"
       halt 403, msg unless Tenter::Utils.dir_exists? params[:site_dir]
-      
+
       secret = Tenter::Utils.secret params[:site_dir]
 
       request_sig = request.env['HTTP_X_HUB_SIGNATURE']
@@ -19,11 +33,15 @@ module Tenter
                      OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'),
                                              secret,
                                              request_body)
-      
+
       msg = "X-Hub-Signature header did not match"
       halt 403, msg unless Rack::Utils.secure_compare computed_sig, request_sig
     end
 
+    # Executes the command
+    #
+    # @since 0.1.1
+    # @api private
     def initiate
       command = Tenter::Utils.command params[:command_name], params[:site_dir]
 
@@ -34,14 +52,19 @@ module Tenter
       msg = ts + "Initiating: #{command["path"]}\n"
       Tenter::Utils.append_to_log command["log"], msg
 
-      pid = if defined?(Bundler) && Bundler.respond_to?(:with_clean_env)
-              Bundler.with_clean_env { command["proc"].call }
+      pid = if defined?(Bundler) && Bundler.respond_to?(:with_original_env)
+              Bundler.with_original_env { command["proc"].call }
             else
               command["proc"].call
             end
       (ENV["APP_ENV"] != "test") ? Process.detach(pid) : Process.wait(pid)
     end
 
+    # Generates the response's HTTP header status and body
+    #
+    # @param message [Symbol] the type of response
+    # @since 0.1.1
+    # @api private
     def notify(message)
       case message
       when :initiated

data/lib/tenter/hooks.rb

@@ -3,6 +3,13 @@
 require "sinatra/base"
 
 module Tenter
+
+  # The Sinatra application
+  #
+  # This sets out the routes for the Sinatra application.
+  #
+  # @since 0.1.1
+  # @api private
   class Hooks < Sinatra::Base
     helpers Tenter::Helpers
 

data/lib/tenter/utils.rb

@@ -3,7 +3,22 @@
 require "yaml"
 
 module Tenter
+
+  # Utility functions for use by Tenter
+  #
+  # @since 0.1.1
+  # @api private
   module Utils
+
+    # Loads configuration data from a YAML file for a given directory
+    #
+    # @note The basename of the YAML file is specified in Tenter's configuration
+    # settings.
+    #
+    # @param site_dir [String] the directory containing the YAML file
+    #
+    # @since 0.1.1
+    # @api private
     def self.config(site_dir)
       @config ||= {}
       @config[site_dir] ||=
@@ -12,14 +27,40 @@ module Tenter
                        Tenter.settings[:config_filename]))
     end
 
+    # Checks if the directory exists
+    #
+    # @note The directory provided must be given relative to the document root.
+    #
+    # @param site_dir [String] the directory to check
+    #
+    # @since 0.1.1
+    # @api private
     def self.dir_exists?(site_dir)
       File.directory? File.join(Tenter.settings[:doc_root], site_dir)
     end
 
+    # Returns the secret value for a particular directory
+    #
+    # @param site_dir [String} the directory
+    #
+    # @since 0.1.1
+    # @api private
     def self.secret(site_dir)
       self.config(site_dir).fetch("secret", nil)
     end
 
+    # Returns the details of the command to execute
+    #
+    # @note The directory provided must be given relative to the document root.
+    #
+    # @param command_name [String] the name of the file representing the
+    #   command
+    # @param site_dir [String} the directory containing the command
+    #
+    # @return [Hash] the details of the command to execute
+    #
+    # @since 0.1.1
+    # @api private
     def self.command(command_name, site_dir)
       site_path = File.join(Tenter.settings[:doc_root], site_dir)
       command = {}
@@ -43,6 +84,13 @@ module Tenter
       return command
     end
 
+    # Appends a statement to the log
+    #
+    # @param log [String] the file representing the log
+    # @param statement [String] the statement to append to the log
+    #
+    # @since 0.1.0
+    # @api private
     def self.append_to_log(log, statement)
       File.write(log, statement, mode: "a")
     end

data/lib/tenter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tenter
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/tenter.gemspec

@@ -3,28 +3,30 @@
 require "./lib/tenter/version"
 
 Gem::Specification.new do |s|
-  s.name = "tenter"
-  s.version = Tenter::VERSION
-  s.authors = ["Michael Camilleri"]
-  s.email = ["mike@inqk.net"]
-  s.summary = "A web app for running user-defined commands"
+  s.name        = "tenter"
+  s.version     = Tenter::VERSION
+  s.authors     = ["Michael Camilleri"]
+  s.email       = ["mike@inqk.net"]
+  s.summary     = "A web app for running user-defined commands"
   s.description = <<-desc.strip.gsub(/\s+/, " ")
     Tenter is a Sinatra-based application that provides webhooks for use by
     GitHub.
   desc
-  s.homepage = "https://github.com/pyrmont/tenter/"
-  s.licenses = "Unlicense"
-  s.required_ruby_version = ">= 2.5"
+  s.homepage    = "https://github.com/pyrmont/tenter/"
+  s.licenses    = "Unlicense"
+  s.files       = Dir["Gemfile", "LICENSE", "tenter.gemspec", "lib/tenter.rb",
+                      "lib/**/*.rb"]
 
-  s.files = Dir["Gemfile", "LICENSE", "tenter.gemspec", "lib/tenter.rb",
-                "lib/**/*.rb"]
-  s.require_paths = ["lib"]
-  
+  s.required_ruby_version         = ">= 2.5"
+  s.require_paths                 = ["lib"]
   s.metadata["allowed_push_host"] = "https://rubygems.org"
 
   s.add_runtime_dependency "sinatra", "~> 2.0"
+  s.add_runtime_dependency "thin", "~> 1.0"
 
-  s.add_development_dependency "minitest", "~> 5.11"
-  s.add_development_dependency "rack-test", "~> 1.1"
-  s.add_development_dependency "rake", "~> 12.3"
+  s.add_development_dependency "minitest", "~> 5.0"
+  s.add_development_dependency "rack-test", "~> 1.0"
+  s.add_development_dependency "rake", "~> 13.0"
+  s.add_development_dependency "redcarpet", "~> 3.0"
+  s.add_development_dependency "yard", "~> 0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tenter
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-08 00:00:00.000000000 Z
+date: 2020-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -24,48 +24,90 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: thin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.11'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.11'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '0.0'
 description: Tenter is a Sinatra-based application that provides webhooks for use
   by GitHub.
 email:
@@ -102,7 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A web app for running user-defined commands