hooks-ruby 0.0.6 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9025d70b78a67040f436318091d556090c7f17e9dffe094b6437bde394ef7010
-  data.tar.gz: 24cf76930b63917dad1795a72113b9cf0646330671983b60bd367cc04d11d015
+  metadata.gz: 2a1dfcc57a6bae5c2e5bd01f7e6165218220f04258ac8fab3ab256b685454bb6
+  data.tar.gz: 724dbe5463d5bf223ef9652e566b448f38a4270d0131446e302236685ba43710
 SHA512:
-  metadata.gz: 0e8acdf59a00128c3a68fb2db10864c0e0bf6a5e454aabceaf824cdf4ba62f8057f166da2dae0f17238a7a280137861ca4ba1da70b33165e6e890becb36be391
-  data.tar.gz: 33178114bcbbda82ecf91cd27bfd7633621f6d7f2ea64fc3891596a8769cc80dac55ceab5c4fc75cd035d2a0188c9da2821743442cfcdbbce0cef2d3d479e6b5
+  metadata.gz: d21c5cce4267f7d5209e495415c90b21375686e1f8d65d9d2080d3d3aa2677344a48cbc1167e4e83bff6a27223e6f12d891a6416ad122b54ee0d36832dd08311
+  data.tar.gz: 8b0fd57ee957d8eb8d58d3556f7f4ab145a7eb5cac82286c2cefd439a77bc28f6e03abe38484154b308b59b3b30e69bd749fec968fe053ebb0b4f9560ae0eb17

data/README.md

@@ -42,7 +42,7 @@ Here is a very high-level overview of how Hooks works:
     health_path: /health
     version_path: /version
 
-    environment: development
+    environment: development # will be overridden by the RACK_ENV environment variable if set
     ```
 
 2. Then in your `config/endpoints` directory, you can define all your webhook endpoints in separate files. Here is an example of a simple endpoint configuration file:
@@ -153,17 +153,22 @@ This example will assume the following directory structure:
 
 ```text
 ├── config/
-│   ├── hooks.yml                 # global hooks config
-│   ├── puma.rb                   # puma config
+│   ├── hooks.yml                    # global hooks config
+│   ├── puma.rb                      # puma config
 │   └── endpoints/
 │       ├── hello.yml
 │       └── goodbye.yml
 └── plugins/
-    ├── handlers/                 # custom handler plugins
+    ├── handlers/                    # custom handler plugins
     │   ├── hello_handler.rb
     │   └── goodbye_handler.rb
+    ├── lifecycle/                   # custom lifecycle plugins (optional)
+    │   └── my_lifecycle_plugin.rb   # custom lifecycle plugin (optional)
+    ├── instruments/                 # custom instrument plugins (optional)
+    │   ├── stats.rb                 # a custom stats instrument plugin (optional)
+    │   └── failbot.rb               # a custom error notifier instrument plugin (optional)
     └── auth/
-        └── goodbye_auth.rb       # custom auth plugin (optional)
+        └── goodbye_auth.rb          # custom auth plugin (optional)
 ```
 
 Let's go through each step in detail.
@@ -174,8 +179,10 @@ First, create a `hooks.yml` file in the `config` directory. This file will defin
 
 ```yaml
 # file: config/hooks.yml
-handler_plugin_dir: ./plugins/handlers
-auth_plugin_dir: ./plugins/auth
+handler_plugin_dir: ./plugins/handlers # Directory for handler plugins
+auth_plugin_dir: ./plugins/auth # Directory for authentication plugins (optional)
+lifecycle_plugin_dir: ./plugins/lifecycle # Directory for lifecycle plugins (optional)
+instruments_plugin_dir: ./plugins/instruments # Directory for instrument plugins (optional)
 
 # Available endpoints
 # Each endpoint configuration file should be placed in the endpoints directory
@@ -189,7 +196,7 @@ health_path: /health
 version_path: /version
 
 # Runtime behavior
-environment: development # or production
+environment: development # or production (will be overridden by the RACK_ENV environment variable if set)
 ```
 
 #### 2. Create your endpoint configurations
@@ -213,6 +220,10 @@ auth:
   type: Goodbye # This is a custom authentication plugin you would define in the plugins/auth
   secret_env_key: GOODBYE_API_KEY # the name of the environment variable containing the secret
   header: Authorization
+
+# Optional additional options for the endpoint (can be anything you want)
+opts:
+  foo: bar
 ```
 
 #### 3. Implement your handler plugins
@@ -251,6 +262,8 @@ class GoodbyeHandler < Hooks::Plugins::Handlers::Base
 end
 ```
 
+See the [Handler Plugins](docs/handler_plugins.md) documentation for more information on how to create your own custom handler plugins and what the values of `payload`, `headers`, and `config` are when the `call` method is invoked.
+
 #### 4. Implement authentication plugins (optional)
 
 If you want to secure your webhook endpoints, you can create custom authentication plugins in the `plugins/auth` directory. Here is an example of a simple authentication plugin for the `/goodbye` endpoint:
@@ -268,7 +281,7 @@ module Hooks
           secret = fetch_secret(config, secret_env_key_name: :secret_env_key)
 
           # check if the Authorization header matches the secret
-          auth_header = headers[config[:header]]
+          auth_header = headers[config[:auth][:header]]
           return false unless auth_header
 
           # compare the Authorization header with the secret
@@ -280,6 +293,8 @@ module Hooks
 end
 ```
 
+To learn more about how you can create your own custom authentication plugins, see the [Auth Plugins](docs/auth_plugins.md) documentation.
+
 #### Summary
 
 What these steps have done is set up a Hooks server that listens for incoming webhook requests at `/webhooks/hello` and `/webhooks/goodbye`. The `/hello` endpoint will respond with a success message without any authentication, while the `/goodbye` endpoint will require a valid `Authorization` header that matches the secret defined in the environment variable `GOODBYE_API_KEY`. Before the `/goodbye` endpoint enters the defined handler, it will first check the authentication plugin to ensure the request is valid.

data/lib/hooks/core/config_loader.rb

@@ -16,7 +16,7 @@ module Hooks
         root_path: "/webhooks",
         health_path: "/health",
         version_path: "/version",
-        environment: "production",
+        environment: ENV.fetch("RACK_ENV", "production"),
         production: true,
         endpoints_dir: "./config/endpoints",
         use_catchall_route: false,

data/lib/hooks/plugins/auth/base.rb

@@ -43,11 +43,30 @@ module Hooks
           secret = ENV[secret_env_key]
 
           if secret.nil? || !secret.is_a?(String) || secret.strip.empty?
-            raise StandardError, "authentication configuration incomplete: missing secret value bound to #{secret_env_key_name}"
+            raise StandardError, "authentication configuration incomplete: missing secret value for environment variable"
           end
 
           return secret.strip
         end
+
+        # Find a header value by name with case-insensitive matching
+        #
+        # @param headers [Hash] HTTP headers from the request
+        # @param header_name [String] Name of the header to find
+        # @return [String, nil] The header value if found, nil otherwise
+        # @note This method performs case-insensitive header matching
+        def self.find_header_value(headers, header_name)
+          return nil unless headers.respond_to?(:each)
+          return nil if header_name.nil? || header_name.strip.empty?
+
+          target_header = header_name.downcase
+          headers.each do |key, value|
+            if key.to_s.downcase == target_header
+              return value.to_s
+            end
+          end
+          nil
+        end
       end
     end
   end

data/lib/hooks/plugins/auth/hmac.rb

@@ -92,26 +92,32 @@ module Hooks
           validator_config = build_config(config)
 
           # Security: Check raw headers BEFORE normalization to detect tampering
-          return false unless headers.respond_to?(:each)
+          unless headers.respond_to?(:each)
+            log.warn("Auth::HMAC validation failed: Invalid headers object")
+            return false
+          end
 
           signature_header = validator_config[:header]
 
-          # Find the signature header with case-insensitive matching but preserve original value
-          raw_signature = nil
-          headers.each do |key, value|
-            if key.to_s.downcase == signature_header.downcase
-              raw_signature = value.to_s
-              break
-            end
-          end
+          # Find the signature header with case-insensitive matching
+          raw_signature = find_header_value(headers, signature_header)
 
-          return false if raw_signature.nil? || raw_signature.empty?
+          if raw_signature.nil? || raw_signature.empty?
+            log.warn("Auth::HMAC validation failed: Missing or empty signature header '#{signature_header}'")
+            return false
+          end
 
           # Security: Reject signatures with leading/trailing whitespace
-          return false if raw_signature != raw_signature.strip
+          if raw_signature != raw_signature.strip
+            log.warn("Auth::HMAC validation failed: Signature contains leading/trailing whitespace")
+            return false
+          end
 
           # Security: Reject signatures containing null bytes or other control characters
-          return false if raw_signature.match?(/[\u0000-\u001f\u007f-\u009f]/)
+          if raw_signature.match?(/[\u0000-\u001f\u007f-\u009f]/)
+            log.warn("Auth::HMAC validation failed: Signature contains control characters")
+            return false
+          end
 
           # Now we can safely normalize headers for the rest of the validation
           normalized_headers = normalize_headers(headers)
@@ -134,7 +140,13 @@ module Hooks
           )
 
           # Use secure comparison to prevent timing attacks
-          Rack::Utils.secure_compare(computed_signature, provided_signature)
+          result = Rack::Utils.secure_compare(computed_signature, provided_signature)
+          if result
+            log.debug("Auth::HMAC validation successful for header '#{signature_header}'")
+          else
+            log.warn("Auth::HMAC validation failed: Signature mismatch")
+          end
+          result
         rescue StandardError => e
           log.error("Auth::HMAC validation failed: #{e.message}")
           false

data/lib/hooks/plugins/auth/shared_secret.rb

@@ -62,37 +62,56 @@ module Hooks
           validator_config = build_config(config)
 
           # Security: Check raw headers BEFORE normalization to detect tampering
-          return false unless headers.respond_to?(:each)
+          unless headers.respond_to?(:each)
+            log.warn("Auth::SharedSecret validation failed: Invalid headers object")
+            return false
+          end
 
           secret_header = validator_config[:header]
 
-          # Find the secret header with case-insensitive matching but preserve original value
-          raw_secret = nil
-          headers.each do |key, value|
-            if key.to_s.downcase == secret_header.downcase
-              raw_secret = value.to_s
-              break
-            end
-          end
+          # Find the secret header with case-insensitive matching
+          raw_secret = find_header_value(headers, secret_header)
 
-          return false if raw_secret.nil? || raw_secret.empty?
+          if raw_secret.nil? || raw_secret.empty?
+            log.warn("Auth::SharedSecret validation failed: Missing or empty secret header '#{secret_header}'")
+            return false
+          end
 
           stripped_secret = raw_secret.strip
 
           # Security: Reject secrets with leading/trailing whitespace
-          return false if raw_secret != stripped_secret
+          if raw_secret != stripped_secret
+            log.warn("Auth::SharedSecret validation failed: Secret contains leading/trailing whitespace")
+            return false
+          end
 
           # Security: Reject secrets containing null bytes or other control characters
-          return false if raw_secret.match?(/[\u0000-\u001f\u007f-\u009f]/)
+          if raw_secret.match?(/[\u0000-\u001f\u007f-\u009f]/)
+            log.warn("Auth::SharedSecret validation failed: Secret contains control characters")
+            return false
+          end
 
           # Use secure comparison to prevent timing attacks
-          Rack::Utils.secure_compare(secret, stripped_secret)
-        rescue StandardError => _e
+          result = Rack::Utils.secure_compare(secret, stripped_secret)
+          if result
+            log.debug("Auth::SharedSecret validation successful for header '#{secret_header}'")
+          else
+            log.warn("Auth::SharedSecret validation failed: Signature mismatch")
+          end
+          result
+        rescue StandardError => e
+          log.error("Auth::SharedSecret validation failed: #{e.message}")
           false
         end
 
         private
 
+        # Short logger accessor for auth module
+        # @return [Hooks::Log] Logger instance
+        def self.log
+          Hooks::Log.instance
+        end
+
         # Build final configuration by merging defaults with provided config
         #
         # Combines default configuration values with user-provided settings,

data/lib/hooks/version.rb

@@ -4,5 +4,5 @@
 module Hooks
   # Current version of the Hooks webhook framework
   # @return [String] The version string following semantic versioning
-  VERSION = "0.0.6".freeze
+  VERSION = "0.1.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hooks-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors:
 - github