chatops-controller 3.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eb59e0c9f0d9fcac1924c0faa12c5b0bfb9e8762
+  data.tar.gz: e7f3395d1105eccabb0e1552e5580a57c04c40fe
+SHA512:
+  metadata.gz: 949d8c2702e391ffe3d1eef5bd45f5a2741a81ff5e1684ed9d376bb07a1ffd5378e29a60c6e654611da25ca9f95d2798a5cd4db503420f698243c2efd6f7e004
+  data.tar.gz: d1d3878610807932e90a3925dbadb9f873098dd3d1e9810ffb37fdc4dffef268707c9fa15f4bd40667f6fe980ab1e25da07d234d6b56983c16d6a57d68d1255c

data/README.md

@@ -0,0 +1,204 @@
+# Chatops Controller
+
+Rails helpers for easy and well-tested Chatops RPC. See the [protocol docs](docs/protocol-description.md)
+for background information on Chatops RPC.
+
+A minimal controller example:
+
+```ruby
+class ChatopsController < ApplicationController
+  include ::Chatops::Controller
+
+  # The default chatops RPC prefix. Clients may replace this.
+  chatops_namespace :echo
+
+  chatop :echo,
+  /(?<text>.*)?/,
+  "<text> - Echo some text back" do
+    jsonrpc_success "Echoing back to you: #{jsonrpc_params[:text]}"
+  end
+end
+```
+
+Some routing boilerplate is required in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  # Replace the controller: argument with your controller's name
+  post "/_chatops/:chatop", controller: "chatops", action: :execute_chatop
+  get  "/_chatops" => "chatops#list"
+end
+```
+
+It's easy to test:
+
+```ruby
+class MyControllerTestCase < ActionController::TestCase
+  include Chatops::Controller::TestCaseHelpers
+  before do
+    chatops_prefix "echo"
+    chatops_auth!
+  end
+
+  def test_it_works
+    chat "echo foo bar baz"
+    assert_equal "foo bar baz", chatop_response
+  end
+end
+```
+
+Before you deploy, add the RPC authentication tokens to your app's environment,
+below.
+
+You're all done. Try `.echo foo`, and you should see your client respond with
+`Echoing back to you: foo`.
+
+A hubot client implementation is available at
+<https://github.com/hubot-scripts/hubot-chatops-rpc>
+
+## Usage
+
+#### Namespaces
+
+Every chatops controller has a namespace. All commands associated with this
+controller will be displayed with `.<namespace>` in chat. The namespace is a
+default chatops RPC prefix and may be overridden by a client.
+
+```
+chatops_namespace :foo
+```
+
+#### Creating Chatops
+
+Creating a chatop is a DSL:
+
+```ruby
+chatop :echo,
+/(?<text>.*)?/,
+"<text> - Echo some text back" do
+  jsonrpc_success "Echoing back to you: #{jsonrpc_params[:text]}"
+end
+```
+
+In this example, we've created a chatop called `echo`. The next argument is a
+regular expression with [named
+captures](http://ruby-doc.org/core-1.9.3/Regexp.html#method-i-named_captures).
+In this example, only one capture group is available, `text`.
+
+The next line is a string, which is a single line of help that will be displayed
+in chat for `.echo`.
+
+The DSL takes a block, which is the code that will run when the chat robot sees
+this regex. Arguments will be available in the `params` hash. `params[:user]`
+and `params[:room_id]` are special, and will be set by the client. `user` will
+always be the login of the user typing the command, and `room_id` will be where
+it was typed.
+
+You can return `jsonrpc_success` with a string to return text to chat. If you
+have an input validation or other handle-able error, you can use
+`jsonrpc_failure` to send a helpful error message.
+
+Chatops are regular old rails controller actions, and you can use niceties like
+`before_action` and friends. `before_action :echo, :load_user` for the above
+case would call `load_user` before running `echo`.
+
+## Authentication
+
+Authentication uses the Chatops v3 public key signing protocol. You'll need
+two environment variables to use this protocol:
+
+`CHATOPS_AUTH_PUBLIC_KEY` is the public key of your chatops client in PEM
+format. This environment variable will be the contents of a `.pub` file,
+newlines and all.
+
+`CHATOPS_AUTH_BASE_URL` is the base URL of your server as the chatops client
+sees it. This is specified as an environment variable since rails will trust
+client headers about a forwarded hostname. For example, if your chatops client
+has added the url `https://example.com/_chatops`, you'd set this to
+`https://example.com`.
+
+You can also optionally set `CHATOPS_AUTH_ALT_PUBLIC_KEY` to a second public key
+which will be accepted. This is helpful when rolling keys.
+
+## Rails compatibility
+
+This gem is intended to work with rails 4.x and 5.x. If you find a version
+with a problem, please report it in an issue.
+
+## Development
+
+Changes are welcome. Getting started:
+
+```
+script/bootstrap
+script/test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution instructions.
+
+## Upgrading from early versions
+
+Early versions of RPC chatops had two major changes:
+
+##### Using Rails' dynamic `:action` routing, which was deprecated in Rails 5.
+
+To work around this, you need to update your router boilerplate:
+
+This:
+
+```ruby
+  post  "/_chatops/:action", controller: "chatops"
+```
+
+Becomes this:
+
+```ruby
+  post  "/_chatops/:chatop", controller: "chatops" action: :execute_chatop
+```
+
+##### Adding a prefix
+
+Version 2 of the Chatops RPC protocol assumes a unique prefix for each endpoint. This decision was made for several reasons:
+
+ * The previous suffix-based system creates semantic ambiguities with keyword arguments
+ * Prefixes allow big improvements to `.help`
+ * Prefixes make regex-clobbering impossible
+
+To upgrade to version 2, upgrade to version 2.x of this gem. To migrate:
+
+ * Migrate your chatops to remove any prefixes you have:
+
+```ruby
+ chatop :foo, "help", /ci build whatever/, do "yay" end
+```
+
+Becomes:
+
+```ruby
+ chatop :foo, "help", /build whatever/, do "yay" end
+```
+
+ * Update your tests:
+
+```ruby
+  chat "ci build foobar"
+```
+
+Becomes:
+
+```ruby
+  chat "build foobar"
+  # or
+  chatops_prefix "ci"
+  chat "ci build foobar"
+```
+
+##### Using public key authentication
+
+Previous versions used a `CHATOPS_ALT_AUTH_TOKEN` as a shared secret. This form
+of authentication was deprecated and the public key form used above is now
+used instead.
+
+### License
+
+MIT. See the accompanying LICENSE file.

data/lib/chatops-controller.rb

@@ -0,0 +1 @@
+require 'chatops/controller'

data/lib/chatops.rb

@@ -0,0 +1,21 @@
+module Chatops
+  def self.public_key
+    ENV[public_key_env_var_name]
+  end
+
+  def self.public_key_env_var_name
+    "CHATOPS_AUTH_PUBLIC_KEY"
+  end
+
+  def self.alt_public_key
+    ENV["CHATOPS_AUTH_ALT_PUBLIC_KEY"]
+  end
+
+  def self.auth_base_url
+    ENV[auth_base_url_env_var_name]
+  end
+
+  def self.auth_base_url_env_var_name
+    "CHATOPS_AUTH_BASE_URL"
+  end
+end

data/lib/chatops/controller.rb

@@ -0,0 +1,209 @@
+require "chatops"
+
+module Chatops
+  module Controller
+    class ConfigurationError < StandardError ; end
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :ensure_valid_chatops_url,       if: :should_authenticate_chatops?
+      before_action :ensure_valid_chatops_timestamp, if: :should_authenticate_chatops?
+      before_action :ensure_valid_chatops_signature, if: :should_authenticate_chatops?
+      before_action :ensure_valid_chatops_nonce,     if: :should_authenticate_chatops?
+      before_action :ensure_chatops_authenticated,   if: :should_authenticate_chatops?
+      before_action :ensure_user_given
+      before_action :ensure_method_exists
+    end
+
+    def list
+      chatops = self.class.chatops
+      chatops.each { |name, hash| hash[:path] = name }
+      render :json => {
+        namespace: self.class.chatops_namespace,
+        help: self.class.chatops_help,
+        error_response: self.class.chatops_error_response,
+        methods: chatops,
+        version: "3" }
+    end
+
+    def process(*args)
+      scrubbed_params = jsonrpc_params.except(
+        :user, :method, :controller, :action, :params, :room_id)
+
+      scrubbed_params.each { |k, v| params[k] = v }
+
+      if params[:chatop].present?
+        params[:action] = params[:chatop]
+        args[0] = params[:action]
+        unless self.respond_to?(params[:chatop].to_sym)
+          raise AbstractController::ActionNotFound
+        end
+      end
+
+      super *args
+    rescue AbstractController::ActionNotFound
+      return jsonrpc_method_not_found
+    end
+
+    def execute_chatop
+      # This needs to exist for route declarations, but we'll be overriding
+      # things in #process to make a method the action.
+    end
+
+    protected
+
+    def jsonrpc_params
+      params["params"] || {}
+    end
+
+    def jsonrpc_success(message)
+      jsonrpc_response :result => message.to_s
+    end
+    alias_method :chatop_send, :jsonrpc_success
+
+    def jsonrpc_parse_error
+      jsonrpc_error(-32700, 500, "Parse error")
+    end
+
+    def jsonrpc_invalid_request
+      jsonrpc_error(-32600, 400, "Invalid request")
+    end
+
+    def jsonrpc_method_not_found
+      jsonrpc_error(-32601, 404, "Method not found")
+    end
+
+    def jsonrpc_invalid_params(message)
+      message ||= "Invalid parameters"
+      jsonrpc_error(-32602, 400, message.to_s)
+    end
+    alias_method :jsonrpc_failure, :jsonrpc_invalid_params
+
+    def jsonrpc_error(number, http_status, message)
+      jsonrpc_response({ :error => { :code => number, :message => message.to_s } }, http_status)
+    end
+
+    def jsonrpc_response(hash, http_status = nil)
+      http_status ||= 200
+      render :status => http_status,
+             :json => { :jsonrpc => "2.0",
+                        :id      => params[:id] }.merge(hash)
+    end
+
+    def ensure_user_given
+      return true unless chatop_names.include?(params[:action].to_sym)
+      return true if params[:user].present?
+      jsonrpc_invalid_params("A username must be supplied as 'user'")
+    end
+
+    def ensure_chatops_authenticated
+      body = request.raw_post || ""
+      signature_string = [@chatops_url, @chatops_nonce, @chatops_timestamp, body].join("\n")
+      # We return this just to aid client debugging.
+      response.headers["Chatops-Signature-String"] = Base64.strict_encode64(signature_string)
+      raise ConfigurationError.new("You need to add a client's public key in .pem format via #{Chatops.public_key_env_var_name}") unless Chatops.public_key.present?
+      if signature_valid?(Chatops.public_key, @chatops_signature, signature_string) ||
+          signature_valid?(Chatops.alt_public_key, @chatops_signature, signature_string)
+          return true
+      end
+      return render :status => :forbidden, :plain => "Not authorized"
+    end
+
+    def ensure_valid_chatops_url
+      unless Chatops.auth_base_url.present?
+        raise ConfigurationError.new("You need to set the server's base URL to authenticate chatops RPC via #{Chatops.auth_base_url_env_var_name}")
+      end
+      if Chatops.auth_base_url[-1] == "/"
+        raise ConfigurationError.new("Don't include a trailing slash in #{Chatops.auth_base_url_env_var_name}; the rails path will be appended and it must match exactly.")
+      end
+      @chatops_url = Chatops.auth_base_url + request.path
+    end
+
+    def ensure_valid_chatops_nonce
+      @chatops_nonce = request.headers["Chatops-Nonce"]
+      return render :status => :forbidden, :plain => "A Chatops-Nonce header is required" unless @chatops_nonce.present?
+    end
+
+    def ensure_valid_chatops_signature
+      signature_header = request.headers["Chatops-Signature"]
+
+      begin
+        # "Chatops-Signature: Signature keyid=foo,signature=abc123" => { "keyid"" => "foo", "signature" => "abc123" }
+        signature_items = signature_header.split(" ", 2)[1].split(",").map { |item| item.split("=", 2) }.to_h
+        @chatops_signature = signature_items["signature"]
+      rescue NoMethodError
+        # The signature header munging, if something's amiss, can produce a `nil` that raises a
+        # no method error. We'll just carry on; the nil signature will raise below
+      end
+
+      unless @chatops_signature.present?
+        return render :status => :forbidden, :plain => "Failed to parse signature header"
+      end
+    end
+
+    def ensure_valid_chatops_timestamp
+      @chatops_timestamp = request.headers["Chatops-Timestamp"]
+      time = Time.iso8601(@chatops_timestamp)
+      if !(time > 1.minute.ago && time < 1.minute.from_now)
+        return render :status => :forbidden, :plain => "Chatops timestamp not within 1 minute of server time: #{@chatops_timestamp} vs #{Time.now.utc.iso8601}"
+      end
+    rescue ArgumentError, TypeError
+        # time parsing or missing can raise these
+      return render :status => :forbidden, :plain => "Invalid Chatops-Timestamp: #{@chatops_timestamp}"
+    end
+
+    def request_is_chatop?
+      (chatop_names + [:list]).include?(params[:action].to_sym)
+    end
+
+    def chatops_test_auth?
+      Rails.env.test? && request.env["CHATOPS_TESTING_AUTH"]
+    end
+
+    def should_authenticate_chatops?
+      request_is_chatop? && !chatops_test_auth?
+    end
+
+    def signature_valid?(key_string, signature, signature_string)
+      return false unless key_string.present?
+      digest = OpenSSL::Digest::SHA256.new
+      decoded_signature = Base64.decode64(signature)
+      public_key = OpenSSL::PKey::RSA.new(key_string)
+      public_key.verify(digest, decoded_signature, signature_string)
+    end
+
+    def ensure_method_exists
+      return jsonrpc_method_not_found unless (chatop_names + [:list]).include?(params[:action].to_sym)
+    end
+
+    def chatop_names
+      self.class.chatops.keys
+    end
+
+    module ClassMethods
+      def chatop(method_name, regex, help, &block)
+        chatops[method_name] = { help: help,
+                                 regex: regex.source,
+                                 params: regex.names }
+        define_method method_name, &block
+      end
+
+      %w{namespace help error_response}.each do |setting|
+        method_name = "chatops_#{setting}".to_sym
+        variable_name = "@#{method_name}".to_sym
+        define_method method_name do |*args|
+          assignment = args.first
+          if assignment.present?
+            instance_variable_set variable_name, assignment
+          end
+          instance_variable_get variable_name.to_sym
+        end
+      end
+
+      def chatops
+        @chatops ||= {}
+        @chatops
+      end
+    end
+  end
+end

data/lib/chatops/controller/rspec.rb

@@ -0,0 +1,5 @@
+require "chatops/controller/test_case"
+
+RSpec.configure do |config|
+  config.include Chatops::Controller::TestCaseHelpers
+end