rails-cloudflare-origin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7407d25d62db057d4b7756bd537f04d307c1dd0da6f4abfbe7688abd8012bb58
+  data.tar.gz: 47b0af6ccf5fe1308c4f996e89b1204e3c355e0355b84eb497dac074b5537e1a
+SHA512:
+  metadata.gz: 88989bfd4e3c1738280d538eff110b5bfc2def01d13c0c3f89b54b473eb2a1f2ea63964aabddbc53694ad4416bab9c74b91b64296d2cc22f2ad608dbcee87fe1
+  data.tar.gz: c2122464fbad49b5158bdd0687bf4109eb7aacd13ea8abfc124cb4910bd4d68fd8d6503682229b96879ea73fedea54d8a3ea120ef4a11d22bc22327be0b8ef2f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kokorono
+
+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,69 @@
+# rails-cloudflare-origin
+
+For a Rails app served through Cloudflare: refuses requests that did not come through Cloudflare, and sets the client IP from `CF-Connecting-IP` on those that did.
+
+Behind Cloudflare and a proxy server in front of the app, `request.remote_ip` tends to return the proxy's own address for every request, because the proxy appends itself to `X-Forwarded-For` and Rails does not trust it. Trusting the proxy and Cloudflare's IP ranges instead means a list to keep current. This gem takes a different route: once a request has proved it came through Cloudflare, the address Cloudflare put in `CF-Connecting-IP` is the visitor.
+
+## Installation
+
+```ruby
+gem "rails-cloudflare-origin"
+```
+
+A Railtie installs the middleware at the top of the stack, above anything the app inserts with `insert_before 0` from an initializer or an environment file, and above Rails' own `HostAuthorization` and `ActionDispatch::SSL`. Nothing else is needed in the app.
+
+## What it does on each request
+
+1. Removes `Forwarded`, `Client-IP`, `X-Forwarded-For`, `X-Real-IP` and `X-Forwarded-Host`. A visitor can send any of these, and conflicting values make Rails raise `ActionDispatch::RemoteIp::IpSpoofAttackError`, which surfaces as a 500. `X-Forwarded-Proto` and `X-Forwarded-Port` stay.
+2. Takes the `X-Origin-Secret` header out of the request, so it never reaches the app, its logs, or an error tracker.
+3. Lets a `GET` or `HEAD` of exactly `/up` through without the secret when it carries no `CF-Ray` header. This is the platform's health check, which reaches the app directly instead of through Cloudflare. A `/up` that came through Cloudflare still needs the secret.
+4. Answers anything else without a matching secret with a `403` and `cache-control: no-store`.
+5. Sets `REMOTE_ADDR` to `CF-Connecting-IP`, so `request.ip` and `request.remote_ip` both return the visitor. A request that carries the secret but no `CF-Connecting-IP`, or one that is not an IP address, raises `CloudflareOrigin::InvalidClientIpError`. Cloudflare always sends that header, so its absence means a zone setting changed, and an error is easier to notice than every visitor quietly sharing one address. The middleware runs above Rails' own error handling, so it reports the error to `Rails.error` itself before raising: any error tracker subscribed to `Rails.error` receives it, and the request ends as a 500 from the app server.
+
+## What it trusts
+
+- **The origin secret.** A request carrying it came through your Cloudflare zone, because only the zone adds it.
+- **`CF-Connecting-IP` on such a request.** Cloudflare refuses a request in which the visitor sent that header themselves (Error 1000), so on a request that passed through the zone, the value is Cloudflare's.
+
+## Cloudflare setup it assumes
+
+- A Request Header Transform Rule on the zone sets `X-Origin-Secret` to the secret the app holds, on every request to the app's hostnames. Generate the value with `openssl rand -hex 32`.
+- The "Remove visitor IP headers" managed transform is off, and no other Transform Rule or Worker removes or rewrites `CF-Connecting-IP`.
+- Leave Pseudo IPv4 off: in Cloudflare's "overwrite headers" mode an IPv6 visitor's address is replaced with a made-up IPv4 address from `240.0.0.0/4`, and the gem records that address.
+
+## Secrets
+
+The gem reads two secrets, each from an environment variable first and from the app's credentials second:
+
+| Secret | Environment variable | Credential |
+| --- | --- | --- |
+| Current, required to switch the gem on | `CLOUDFLARE_ORIGIN_SECRET` | `cloudflare_origin_secret` |
+| Previous, being rotated out, optional | `CLOUDFLARE_ORIGIN_SECRET_PREVIOUS` | `cloudflare_origin_secret_previous` |
+
+Each secret is resolved on its own: a non-blank environment variable wins over the credential. A variable left set on the host therefore overrides the credential without any warning, so a stale one keeps an old value in force after you rotate the credential.
+
+Both secrets are accepted, so the value rotates without an outage: set the new value as the current secret and the old one as the previous secret, deploy, switch the Transform Rule to the new value, then remove the previous one.
+
+A secret that is present but shorter than 32 characters fails the boot, so a broken value stops a deploy instead of answering every request with a 403. A blank secret counts as absent.
+
+## When it is on
+
+The middleware is installed only when a current secret is present, and never in the `development` and `test` environments, even when a secret is set, so local requests and specs see the headers they send.
+
+When no current secret is present, the gem installs nothing. Outside `development` and `test` it logs a warning at boot saying the middleware is not installed. An asset build that boots without credentials has no secret, so it is simply off.
+
+## Requirements
+
+Ruby 4.0 or newer and Rails 8.1 or newer. The gem targets the latest Ruby and Rails only, and these floors move up with each release.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec standardrb
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/cloudflare_origin/middleware.rb

@@ -0,0 +1,115 @@
+require "active_support"
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/object/blank"
+require "active_support/security_utils"
+require "digest"
+require "resolv"
+
+module CloudflareOrigin
+  # Raised for a request that carries the origin secret but no usable CF-Connecting-IP. Cloudflare
+  # always sends that header, so its absence means a zone setting or Worker changed it; failing loudly
+  # beats recording the proxy's address as every visitor's without anyone noticing.
+  class InvalidClientIpError < StandardError; end
+
+  # Answers only requests that came through Cloudflare, and takes the client IP from
+  # CF-Connecting-IP on those. A Request Header Transform Rule on the zone sets X-Origin-Secret to a
+  # secret the app also holds, so a request that reached the origin directly lacks it and gets a 403.
+  #
+  # Two secrets are accepted so the value can rotate without an outage: set the new one as the
+  # current secret and the old one as the previous secret, deploy, switch the Cloudflare rule to the
+  # new value, then drop the previous one.
+  #
+  # A GET or HEAD of /up stays open to the platform's health check, which reaches the app directly
+  # and cannot carry the header. A /up that came through Cloudflare (it carries CF-Ray) still needs
+  # the secret, so a smoke check against the public hostname fails when the rule is missing or wrong.
+  class Middleware
+    SECRET_HEADER = "HTTP_X_ORIGIN_SECRET".freeze
+
+    # With these gone and REMOTE_ADDR set to the visitor, Rack's request.ip and Rails' remote_ip
+    # both return REMOTE_ADDR, and Rails' spoofing check has nothing to compare, so a forged header
+    # can neither choose the client IP nor raise IpSpoofAttackError. X-Real-IP goes too, because some error trackers take the client IP from it.
+    # X-Forwarded-Proto and X-Forwarded-Port stay, since Cloudflare and the proxy server in front of
+    # the app set them.
+    FORWARDING_HEADERS = %w[
+      HTTP_CLIENT_IP
+      HTTP_FORWARDED
+      HTTP_X_FORWARDED_FOR
+      HTTP_X_FORWARDED_HOST
+      HTTP_X_REAL_IP
+    ].freeze
+
+    CLIENT_IP_HEADER = "HTTP_CF_CONNECTING_IP".freeze
+
+    HEALTH_CHECK_METHODS = %w[GET HEAD].freeze
+
+    # `openssl rand -hex 32` makes 64 characters, so anything shorter than half of that is a
+    # placeholder or a paste gone wrong, and guessable.
+    MINIMUM_LENGTH = 32
+
+    def initialize(app, current:, previous:)
+      @app = app
+      current, previous = current.to_s, previous.to_s
+      # A blank value would 403 every page. Failing at boot stops the release, so no machine is
+      # replaced.
+      raise ArgumentError, "the current Cloudflare origin secret is blank" if current.blank?
+
+      secrets = [current, previous].compact_blank
+      if secrets.any? { it.length < MINIMUM_LENGTH }
+        raise ArgumentError, "a Cloudflare origin secret is shorter than #{MINIMUM_LENGTH} characters"
+      end
+
+      @digests = secrets.map { digest it }
+    end
+
+    def call(env)
+      # Removed before the /up decision, so the unguarded health check path is covered too.
+      FORWARDING_HEADERS.each { env.delete it }
+      # Removed before anything downstream runs, so the value never reaches logs or error reports.
+      header = env.delete SECRET_HEADER
+      return @app.call env if rails_health_check? env
+      return forbidden unless header
+
+      given = digest header
+      return forbidden unless @digests.any? { ActiveSupport::SecurityUtils.fixed_length_secure_compare it, given }
+
+      env["REMOTE_ADDR"] = client_ip env
+      @app.call env
+    end
+
+    private
+
+    def rails_health_check?(env)
+      env["PATH_INFO"] == "/up" && HEALTH_CHECK_METHODS.include?(env["REQUEST_METHOD"]) && !env.key?("HTTP_CF_RAY")
+    end
+
+    def client_ip(env)
+      value = env[CLIENT_IP_HEADER]
+      raise InvalidClientIpError, "CF-Connecting-IP is missing" if value.blank?
+      raise InvalidClientIpError, "CF-Connecting-IP is not an IP address" unless ip_address? value
+
+      value
+    rescue InvalidClientIpError => error
+      # This middleware sits above ActionDispatch::Executor, so Rails' own error reporting never sees
+      # the raise; only an app-server hook would. Reporting here reaches every Rails.error subscriber.
+      ActiveSupport.error_reporter.report error, handled: false, source: "rails-cloudflare-origin"
+      raise
+    end
+
+    # The Resolv patterns match a bare address only, where IPAddr.new would also take a CIDR range.
+    def ip_address?(value)
+      value.match?(Resolv::IPv4::Regex) || value.match?(Resolv::IPv6::Regex)
+    end
+
+    # A fresh response each time, so a caller that adds headers to one cannot change the next. Never
+    # cached, so a 403 served while the rule's value is wrong does not outlive the fix at
+    # Cloudflare's edge.
+    def forbidden
+      [403, {"content-type" => "text/plain", "cache-control" => "no-store"}, ["Forbidden"]]
+    end
+
+    # Compared as fixed-length digests, so values of different lengths neither raise nor return early.
+    def digest(value)
+      Digest::SHA256.digest value
+    end
+  end
+end

data/lib/cloudflare_origin/railtie.rb

@@ -0,0 +1,25 @@
+require "rails/railtie"
+
+module CloudflareOrigin
+  class Railtie < Rails::Railtie
+    initializer "cloudflare_origin.middleware", after: :load_config_initializers do |app|
+      next if Rails.env.local?
+
+      current = Railtie.secret app, :cloudflare_origin_secret
+      if current.blank?
+        Rails.logger.warn "rails-cloudflare-origin: middleware not installed because no origin secret is configured"
+        next
+      end
+
+      app.config.middleware.insert_before 0, Middleware,
+        current:,
+        previous: Railtie.secret(app, :cloudflare_origin_secret_previous)
+    end
+
+    # The environment variable wins when set, so a host can supply the secret without editing
+    # credentials. A stale variable left on the host therefore overrides a rotated credential.
+    def self.secret(app, name)
+      ENV[name.to_s.upcase].presence || app.credentials[name]
+    end
+  end
+end

data/lib/cloudflare_origin/version.rb

@@ -0,0 +1,3 @@
+module CloudflareOrigin
+  VERSION = "0.1.0".freeze
+end

data/lib/cloudflare_origin.rb

@@ -0,0 +1,3 @@
+require "cloudflare_origin/version"
+require "cloudflare_origin/middleware"
+require "cloudflare_origin/railtie"

data/lib/rails-cloudflare-origin.rb

@@ -0,0 +1 @@
+require "cloudflare_origin"

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: rails-cloudflare-origin
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kokorono
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+description: A Rack middleware, installed by a Railtie at the top of the stack, that
+  requires a Cloudflare-added origin secret, strips client IP headers a visitor can
+  forge, and sets the client IP from CF-Connecting-IP.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/cloudflare_origin.rb
+- lib/cloudflare_origin/middleware.rb
+- lib/cloudflare_origin/railtie.rb
+- lib/cloudflare_origin/version.rb
+- lib/rails-cloudflare-origin.rb
+homepage: https://github.com/kokorono-group/rails-cloudflare-origin
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/kokorono-group/rails-cloudflare-origin/issues
+  changelog_uri: https://github.com/kokorono-group/rails-cloudflare-origin/releases
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/kokorono-group/rails-cloudflare-origin
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Refuse requests that bypass Cloudflare and take the client IP from CF-Connecting-IP
+test_files: []