action_ip_filter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a0156496085eb4b1b02b0c96bc4e16859dddc35d2cf9920c9f34ffba6f2f32c
+  data.tar.gz: 522544d5021bf15706737c4ecbd32dc783ccfee77bad855d752af7a7653f06e5
+SHA512:
+  metadata.gz: 0463f7af276564a3f6d2a1175cc86ad2d0a0236261015befc3f73ba992f29994b85a36d4c86237e8df9d031cffcb6ea50deda34cf597608a9fc20cd742c2a3d2
+  data.tar.gz: e89379d17ac2c97b1607046405ef2366502a71700c53daa06f9ed3fa7fe5a8ca4d81faee1c998f784705c97e20723fa47050baeb359d3cac11223a2dd33acd63

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-28
+
+- Initial release
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 SmartBank, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,216 @@
+# action_ip_filter
+
+A lightweight gem that provides IP address restrictions for Rails controllers at the action level.
+
+## Why action_ip_filter?
+
+Unlike Rack middleware solutions (e.g., `rack-attack`), action_ip_filter operates at the controller level:
+
+| Feature | rack-attack | action_ip_filter |
+|---------|-------------|----------------|
+| Layer | Rack middleware (all requests) | Controller before_action |
+| Granularity | Path/IP based | Controller/Action based |
+| Overhead | Every request evaluated | Only specified actions |
+| Use case | DDoS protection, rate limiting | Admin panels, webhooks |
+
+**Use this gem when you need:**
+- IP restrictions on specific controller actions only
+- Minimal overhead (no processing for unrestricted endpoints)
+- Simple, declarative configuration per controller
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "action_ip_filter"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Usage
+
+Include the concern and use `restrict_ip` to protect specific actions:
+
+```ruby
+class AdminController < ApplicationController
+  include ActionIpFilter::IpFilterable
+
+  restrict_ip :index, :show, allowed_ips: %w[192.0.2.0/24 198.51.100.1]
+
+  def index
+    # Only accessible from 192.0.2.0/24 or 198.51.100.1
+  end
+
+  def show
+    # Also restricted
+  end
+
+  def public_action
+    # Not restricted
+  end
+end
+```
+
+### Restrict All Actions
+
+Use `restrict_ip_for_all` to protect all actions with optional exceptions:
+
+```ruby
+class WebhooksController < ApplicationController
+  include ActionIpFilter::IpFilterable
+
+  restrict_ip_for_all allowed_ips: ENV["WEBHOOK_ALLOWED_IPS"].to_s.split(","),
+                      except: [:health_check]
+
+  def stripe
+    # Restricted
+  end
+
+  def health_check
+    # Not restricted
+  end
+end
+```
+
+### Dynamic IP Lists
+
+Pass a Proc for dynamic IP resolution:
+
+```ruby
+class SecureController < ApplicationController
+  include ActionIpFilter::IpFilterable
+
+  restrict_ip :sensitive_action,
+    allowed_ips: -> { Rails.application.credentials.dig(:allowed_ips) || [] }
+end
+```
+
+### Custom Denial Handler
+
+Customize the response when access is denied. The block is executed via `instance_exec` in the controller context, so you can use controller methods like `head`, `render`, etc. The request object is passed as an argument:
+
+```ruby
+class ApiController < ApplicationController
+  include ActionIpFilter::IpFilterable
+
+  restrict_ip :create,
+    allowed_ips: %w[192.0.2.0/24],
+    on_denied: -> { render json: { error: "Access denied from #{request.remote_ip}" }, status: :forbidden }
+end
+```
+
+## Configuration
+
+Configure global settings in an initializer:
+
+```ruby
+# config/initializers/action_ip_filter.rb
+ActionIpFilter.configure do |config|
+  # Custom IP resolver (default: request.remote_ip)
+  config.ip_resolver = ->(request) {
+    request.headers["X-Forwarded-For"]&.split(",")&.first&.strip || request.remote_ip
+  }
+
+  # Default denial handler (receives request, executed via instance_exec in controller)
+  config.on_denied = -> { head :forbidden }
+
+  # Logger for denied requests
+  config.logger = Rails.logger
+
+  # Enable/disable denial logging (default: true)
+  config.log_denials = true
+end
+```
+
+### Default Values
+
+| Option | Default                             | Description                                        |
+|--------|-------------------------------------|----------------------------------------------------|
+| `ip_resolver` | `->(request) { request.remote_ip }` | Proc that extracts client IP from request |
+| `on_denied` | `-> { head :forbidden }`            | Handler called when access is denied (returns 403) |
+| `logger` | `Rails.logger`                      | Logger instance for denied request logging |
+| `log_denials` | `true`                              | Whether to log denied requests as warn level |
+
+## Testing
+
+### Bypass IP Filter in Tests
+
+Use the test helpers to bypass IP restrictions:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.include ActionIpFilter::TestHelpers
+
+  # Option 1: Globally bypass in all tests
+  config.before do
+    ActionIpFilter.test_mode = true
+  end
+end
+```
+
+Or use helpers for specific tests:
+
+```ruby
+RSpec.describe "Admin", type: :request do
+  include ActionIpFilter::TestHelpers
+
+  describe "GET /admin" do
+    it "allows access when filter is bypassed" do
+      without_ip_filter do
+        get "/admin"
+        expect(response).to have_http_status(:ok)
+      end
+    end
+
+    it "denies access from unauthorized IP" do
+      with_ip_filter do
+        get "/admin"
+        expect(response).to have_http_status(:not_found)
+      end
+    end
+  end
+end
+```
+
+## Supported IP Formats
+
+- Single IPv4: `192.0.2.1`
+- Single IPv6: `::1`, `2001:db8::1`
+- CIDR notation: `192.0.2.0/24`
+- IPv6 CIDR: `2001:db8::/32`
+
+## Logging
+
+When `log_denials` is enabled (default), denied requests are logged:
+
+```
+[ActionIpFilter] Access denied for IP: 192.0.2.1 on MyController#index
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run type checker
+bundle exec rake rbs
+
+# Run linter
+bundle exec standardrb
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/action_ip_filter/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ActionIpFilter
+  class Configuration
+    # @rbs @ip_resolver: ^(ActionDispatch::Request) -> String?
+    # @rbs @on_denied: ^() -> void
+    # @rbs @logger: Logger?
+    # @rbs @log_denials: bool
+
+    attr_accessor :ip_resolver #: ^(ActionDispatch::Request) -> String?
+    attr_accessor :on_denied #: ^() -> void
+    attr_accessor :logger #: Logger?
+    attr_accessor :log_denials #: bool
+
+    # @rbs return: void
+    def initialize
+      @ip_resolver = ->(request) { request.remote_ip }
+      @on_denied = -> { head :forbidden } # steep:ignore NoMethod
+      @logger = nil
+      @log_denials = true
+    end
+  end
+
+  class << self
+    # @rbs @configuration: Configuration?
+
+    # @rbs return: Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @rbs () { (Configuration) -> void } -> void
+    def configure
+      yield(configuration)
+    end
+
+    # @rbs return: void
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/action_ip_filter/ip_filterable.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ActionIpFilter
+  module IpFilterable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :action_ip_restrictions, default: {}
+    end
+
+    # @rbs!
+    #   type restriction_options = { allowed_ips: Array[String] | ^() -> Array[String], on_denied: (^() -> void)? }
+    #   def action_ip_restrictions: () -> Hash[Symbol, untyped]
+    #   def action_ip_restrictions=: (Hash[Symbol, untyped]) -> void
+
+    # @rbs!
+    #   def request: () -> ActionDispatch::Request
+    #   def action_name: () -> String
+    #   def instance_exec: (*untyped) { () -> void } -> void
+    #   def before_action: (*untyped, **untyped) -> void
+
+    class_methods do
+      # @rbs *actions: Symbol
+      # @rbs allowed_ips: Array[String] | ^() -> Array[String]
+      # @rbs on_denied: (^() -> void)?
+      # @rbs return: void
+      def restrict_ip(*actions, allowed_ips:, on_denied: nil)
+        actions.flatten.each do |action|
+          self.action_ip_restrictions = action_ip_restrictions.merge(action.to_sym => {allowed_ips:, on_denied:})
+          before_action -> { check_ip_restriction(action) }, only: action
+        end
+      end
+
+      # @rbs allowed_ips: Array[String] | ^() -> Array[String]
+      # @rbs except: Array[Symbol]
+      # @rbs on_denied: (^() -> void)?
+      # @rbs return: void
+      def restrict_ip_for_all(allowed_ips:, except: [], on_denied: nil)
+        # note: hyphen is not allowed in method (i.e., action) names, so it's safe to use it as a marker
+        self.action_ip_restrictions = action_ip_restrictions.merge("all-marker": {allowed_ips:, on_denied:})
+        before_action :check_ip_restriction_for_all, except:
+      end
+    end
+
+    private
+
+    # @rbs action: Symbol
+    # @rbs return: void
+    def check_ip_restriction(action)
+      verify_ip_access(action_ip_restrictions[action.to_sym])
+    end
+
+    # @rbs return: void
+    def check_ip_restriction_for_all
+      verify_ip_access(action_ip_restrictions[:"all-marker"])
+    end
+
+    # @rbs restriction: restriction_options?
+    # @rbs return: void
+    def verify_ip_access(restriction)
+      return if restriction.nil? || ActionIpFilter.test_mode?
+
+      client_ip = ActionIpFilter.configuration.ip_resolver.call(request)
+      allowed_ips = resolve_allowed_ips(restriction[:allowed_ips])
+
+      unless IpMatcher.allowed?(client_ip, allowed_ips)
+        log_ip_denial(client_ip)
+        on_denied = restriction[:on_denied] || ActionIpFilter.configuration.on_denied
+        instance_exec(&on_denied)
+      end
+    end
+
+    # @rbs allowed_ips: Array[String] | ^() -> Array[String]
+    # @rbs return: Array[String]
+    def resolve_allowed_ips(allowed_ips)
+      case allowed_ips
+      when Proc
+        instance_exec(&allowed_ips) #: Array[String]
+      else
+        Array(allowed_ips)
+      end
+    end
+
+    # @rbs client_ip: String?
+    # @rbs return: void
+    def log_ip_denial(client_ip)
+      return unless ActionIpFilter.configuration.log_denials
+
+      logger = ActionIpFilter.configuration.logger
+      return if logger.nil?
+
+      logger.warn do
+        "[ActionIpFilter] Access denied for IP: #{client_ip} on #{self.class.name}##{action_name}"
+      end
+    end
+  end
+end

data/lib/action_ip_filter/ip_matcher.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module ActionIpFilter
+  module IpMatcher
+    class << self
+      # @rbs client_ip: String?
+      # @rbs allowed_ips: Array[String]
+      # @rbs return: bool
+      def allowed?(client_ip, allowed_ips)
+        return false if client_ip.nil? || client_ip.empty? || allowed_ips.empty?
+
+        client_addr = parse_ip(client_ip)
+        return false unless client_addr
+
+        allowed_ips.any? do |allowed_ip|
+          match?(client_addr, allowed_ip)
+        end
+      end
+
+      private
+
+      # @rbs ip_string: String
+      # @rbs return: IPAddr?
+      def parse_ip(ip_string)
+        IPAddr.new(ip_string)
+      rescue IPAddr::InvalidAddressError
+        nil
+      end
+
+      # @rbs client_addr: IPAddr
+      # @rbs allowed_ip: String
+      # @rbs return: bool
+      def match?(client_addr, allowed_ip)
+        if allowed_ip.include?("/")
+          range = IPAddr.new(allowed_ip)
+          range.include?(client_addr)
+        else
+          allowed_addr = IPAddr.new(allowed_ip)
+          client_addr == allowed_addr
+        end
+      rescue IPAddr::InvalidAddressError
+        false
+      end
+    end
+  end
+end

data/lib/action_ip_filter/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActionIpFilter
+  class Railtie < Rails::Railtie
+    initializer "action_ip_filter.configure" do
+      ActionIpFilter.configuration.logger ||= Rails.logger
+    end
+  end
+end

data/lib/action_ip_filter/test_helpers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActionIpFilter
+  module TestHelpers
+    # @rbs [T] () { () -> T } -> T
+    def without_ip_filter(&block)
+      original_mode = ActionIpFilter.test_mode?
+      ActionIpFilter.test_mode = true
+      block.call
+    ensure
+      ActionIpFilter.test_mode = original_mode
+    end
+
+    # @rbs [T] () { () -> T } -> T
+    def with_ip_filter(&block)
+      original_mode = ActionIpFilter.test_mode?
+      ActionIpFilter.test_mode = false
+      block.call
+    ensure
+      ActionIpFilter.test_mode = original_mode
+    end
+
+    # @rbs return: void
+    def enable_ip_filter_test_mode!
+      ActionIpFilter.test_mode = true
+    end
+
+    # @rbs return: void
+    def disable_ip_filter_test_mode!
+      ActionIpFilter.test_mode = false
+    end
+  end
+end

data/lib/action_ip_filter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActionIpFilter
+  VERSION = "0.1.0" #: String
+end

data/lib/action_ip_filter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+
+require_relative "action_ip_filter/version"
+require_relative "action_ip_filter/configuration"
+require_relative "action_ip_filter/ip_matcher"
+require_relative "action_ip_filter/ip_filterable"
+require_relative "action_ip_filter/test_helpers"
+require_relative "action_ip_filter/railtie" if defined?(Rails::Railtie)
+
+module ActionIpFilter
+  # @rbs!
+  #   def self.test_mode=: (bool) -> bool
+
+  class << self
+    # @rbs @test_mode: bool
+
+    attr_accessor :test_mode #: bool
+
+    # @rbs return: bool
+    def test_mode?
+      @test_mode == true
+    end
+  end
+
+  self.test_mode = false
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: action_ip_filter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SmartBank, Inc.
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        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: rspec
+  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: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.52'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.52'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rbs-inline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+description: A lightweight concern that allows IP address restrictions on specific
+  controller actions. Unlike Rack middleware solutions, this operates at the controller
+  level for minimal overhead.
+email:
+- moznion@mail.moznion.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/action_ip_filter.rb
+- lib/action_ip_filter/configuration.rb
+- lib/action_ip_filter/ip_filterable.rb
+- lib/action_ip_filter/ip_matcher.rb
+- lib/action_ip_filter/railtie.rb
+- lib/action_ip_filter/test_helpers.rb
+- lib/action_ip_filter/version.rb
+homepage: https://github.com/smartbank-inc/action_ip_filter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/smartbank-inc/action_ip_filter
+  source_code_uri: https://github.com/smartbank-inc/action_ip_filter
+  changelog_uri: https://github.com/smartbank-inc/action_ip_filter/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: IP address restriction concern for Rails controllers
+test_files: []