add IP filtering example

Author: GrantBirki

docs/auth_plugins.md

@@ -417,3 +417,34 @@ auth:
   secret_env_key: SUPER_COOL_SECRET # the name of the environment variable containing the shared secret - used by `fetch_secret(config)` in the plugin
   header: Authorization
 ```
+
+Here is a mini example of how you might do some sort of IP filtering in a custom auth plugin:
+
+```ruby
+# frozen_string_literal: true
+# Example custom auth plugin for IP filtering
+module Hooks
+  module Plugins
+    module Auth
+      class IpFilteringPlugin < Base
+        def self.valid?(payload:, headers:, config:)
+          # Get the allowed IPs from the configuration (opts is a hash containing additional options that can be set in any endpoint configuration)
+          allowed_ips = config.dig(:opts, :allowed_ips) || []
+
+          # Get the request IP from headers or payload
+          # Find the IP via the request headers with case-insensitive matching - this is a helper method available in the base class
+          # so it is available to all auth plugins.
+          # This example assumes the IP is in the "X-Forwarded-For" header, which is common for proxied requests
+          request_ip = find_header_value(headers, "X-Forwarded-For")
+
+          # If the request IP is not found, return false
+          return false unless request_ip
+
+          # Return true if the request IP is in the allowed IPs list
+          allowed_ips.include?(request_ip)
+        end
+      end
+    end
+  end
+end
+```

lib/hooks/app/rack_env_builder.rb

@@ -72,6 +72,8 @@ def build_base_environment
       end
 
       # Add HTTP headers to the environment with proper Rack naming convention
+      # Note: This will generally add headers like HTTP_X_CUSTOM_HEADER. For example, the HTTP_X_FORWARDED_FOR
+      # is a common header that is used to pass the original client IP address through proxies.
       #
       # @param rack_env [Hash] Environment hash to modify
       def add_http_headers(rack_env)