firebase_hosting_client_ip 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e48d62e28d0187e3caf5bb678495c06a775b4b51c9c1d76a28eaa94a54c93b1c
-  data.tar.gz: 874542528ec7e86f365808c93fa569d551c00d7207ef40bc0d43dc4f9b418907
+  metadata.gz: 503e4ef653bdeaaf7f0bba3d5fd3c3df832fe68a9f04cea4439d80b729fa10a0
+  data.tar.gz: b42cb16f12bbcc93125259c4068e195f6fa198df0f8db2437703f42520632aa0
 SHA512:
-  metadata.gz: 5c06f5e782a887ac0a00a74b64d4bef9cda8edaf24dac7c72aaf7225375cfa4534a77cf9f9a5d84c19a0bdd059edf1a02da67ac3115c92df9bd0e777a7f7b3f3
-  data.tar.gz: cea83633e7ec6cd55b50ca8ca7a64c0ae4e1c148344e8dfb107302518ac31c559f655ba58193ba91f5646dbd0c828bcbfb970c64fdf059046669b7c8f2151906
+  metadata.gz: 948ee3ad5edf5d3548e9ff56a91da34319c6c1c9dd4e73f6e1bc1781359f9d6d822dbfb296b6753526ce1f72bdc3879593d7102320f4e7a44d4c1cb2b766a935
+  data.tar.gz: cffdbf0f0d716272553e89c19a3cb406a029fd8e55565406fa051a7214733539d67408f37a8c32935a35a78c912f9a5f78b09a527f95b33b83ee2535ebf2ae57

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.1"
+  ".": "1.0.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [1.0.0](https://github.com/quintsys/firebase_hosting_client_ip/compare/v0.3.1...v1.0.0) (2026-09-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* REMOTE_ADDR is no longer overwritten; read the client IP from request.remote_ip rather than request.ip or REMOTE_ADDR. The X-Forwarded-For fallback has been removed -- when Fastly-Client-IP is absent, request.remote_ip returns Rails' own value or the configured sentinel.
+
+### Features
+
+* trust only Fastly-Client-IP and stop rewriting REMOTE_ADDR ([#44](https://github.com/quintsys/firebase_hosting_client_ip/issues/44)) ([ad1c5ce](https://github.com/quintsys/firebase_hosting_client_ip/commit/ad1c5ceea4fbcf3b08fe524a9723fe77738f4861))
+
 ## [0.3.1](https://github.com/quintsys/firebase_hosting_client_ip/compare/v0.3.0...v0.3.1) (2025-12-23)
 
 

data/README.md

@@ -2,114 +2,238 @@
 
 [![Gem Version](https://badge.fury.io/rb/firebase_hosting_client_ip.svg)](https://badge.fury.io/rb/firebase_hosting_client_ip)
 
-A Rails middleware gem that normalizes client IP addresses when your Rails application is deployed behind Firebase Hosting.
+Rails middleware that makes `request.remote_ip` return the real client IP when your application is deployed behind Firebase Hosting.
 
 ## Problem
 
-When a Rails application is deployed behind Firebase Hosting, the original client IP address is obscured by proxy layers. Rails' default `ActionDispatch::RemoteIp` middleware may not correctly identify the true client IP due to the specific header precedence used by Firebase Hosting's infrastructure.
+Firebase Hosting fronts your application with Fastly (undocumented, not configurable — every Firebase Hosting site gets it). When the origin is Cloud Run, nothing your application sees at the socket belongs to the client: every hop in front of it is Google infrastructure, and each one looks like a legitimate caller.
 
-This gem provides a middleware that implements a heuristic precedence order specifically designed for Firebase Hosting's proxy chain, ensuring `request.remote_ip` returns the correct client IP address.
+```mermaid
+flowchart TB
+    client["👤 Client<br/>203.0.113.99"]
+    fastly["Firebase Hosting<br/>Fastly edge"]
+    gfe["Google Front End<br/>34.96.0.1"]
+    rails["Cloud Run container<br/>Rails app"]
 
-## Supported Architecture
+    client -- "connects" --> fastly
+    fastly -- "sets Fastly-Client-IP: 203.0.113.99" --> gfe
+    gfe -- "appends itself to X-Forwarded-For" --> rails
 
-This gem is designed for the following architecture:
+    rails --> arrives
 
-```
-Client → Firebase Hosting → Rails Application
-```
+    subgraph arrives["What arrives at Rails"]
+        direction LR
+        a1["REMOTE_ADDR &nbsp; 169.254.1.1 &nbsp; — the peer that connected"]
+        a2["X-Forwarded-For &nbsp; 203.0.113.99, 34.96.0.1"]
+        a3["Fastly-Client-IP &nbsp; 203.0.113.99 &nbsp; — the actual client"]
+    end
 
-Firebase Hosting uses Fastly CDN behind the scenes (this is not a documented feature and is not configurable - all Firebase Hosting users get Fastly CDN automatically). The middleware handles the `HTTP_FASTLY_CLIENT_IP` header that Fastly provides, as well as the `HTTP_X_FORWARDED_FOR` header from the proxy chain.
+    arrives --> stock
+    arrives --> gem
 
-## Intended Use Cases
+    stock["❌ Stock Rails<br/>request.remote_ip → 34.96.0.1<br/>a Google address, not your user"]
+    gem["✅ With this gem<br/>request.remote_ip → 203.0.113.99"]
 
-This middleware is useful for:
+    classDef bad fill:#ffebe9,stroke:#cf222e,color:#1f2328
+    classDef good fill:#dafbe1,stroke:#1a7f37,color:#1f2328
+    class stock bad
+    class gem good
+```
 
-- **Logging**: Accurately log client IP addresses for audit trails and debugging
-- **Analytics**: Track user locations and behavior based on correct IP geolocation
-- **User Experience**: Personalize content based on user location
-- **Security**: Implement IP-based rate limiting or access controls
+Rails resolves `remote_ip` by walking `X-Forwarded-For` right-to-left, discarding entries it recognizes as *trusted* proxies. A Google front-end address is public and appears in no trusted-proxy list, so the walk stops there and reports it as the client. Every request then looks like it came from the same handful of Google addresses — which quietly breaks rate limiting, IP allowlists, geolocation, and audit trails.
 
-## Security Disclaimer
+Fastly sets `Fastly-Client-IP` to the end user's address. In this architecture it is the only trustworthy source, and this gem's entire job is to make Rails use it.
 
-**IMPORTANT**: This middleware trusts HTTP headers (`HTTP_FASTLY_CLIENT_IP` and `HTTP_X_FORWARDED_FOR`) to determine the client IP address. These headers can be spoofed by clients if they have direct access to your application.
+## What it does
 
-**This middleware is only safe to use when:**
-- Your Rails application is deployed behind Firebase Hosting (or a trusted proxy/CDN)
-- Direct access to your application is blocked (e.g., via firewall rules)
-- You trust the proxy infrastructure to set these headers correctly
+One thing:
 
-**Do not use this middleware if:**
-- Your application is directly accessible from the internet
-- You cannot guarantee that requests pass through Firebase Hosting
-- You need strict security guarantees about IP address authenticity
+> If `Fastly-Client-IP` is present and contains a valid IP address, `request.remote_ip` returns it. Otherwise the gem gets out of the way.
 
-For production deployments, ensure your application only accepts traffic through Firebase Hosting and cannot be accessed directly.
+- **`REMOTE_ADDR` is never modified.** `request.ip` keeps reporting the actual peer address; `request.remote_ip` reports the client. They describe different layers, and conflating them was the design mistake in 0.x.
+- **`X-Forwarded-For` is never consulted.** It cannot distinguish the client from Google's infrastructure, and it is attacker-controlled if your service can be reached directly.
+- **IP values are validated, not rewritten.** The header's own spelling is passed through — an expanded IPv6 address is not silently compressed.
+
+The middleware is inserted automatically after `ActionDispatch::RemoteIp`, where it replaces the value Rails computed. No application changes are required, and anything reading `request.remote_ip` — your code, Rack::Attack, audit logging, rate limiters — picks it up.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```ruby
+gem "firebase_hosting_client_ip"
+```
+
+Requires Ruby >= 3.2 and Rails >= 7.0.
+
+## Usage
 
 ```ruby
-gem 'firebase_hosting_client_ip'
+class ApplicationController < ActionController::Base
+  def index
+    Rails.logger.info "Request from: #{request.remote_ip}"
+  end
+end
 ```
 
-And then execute:
+### Configuration
+
+There is one option, and it controls a single decision: when there is no trustworthy Fastly IP, does Rails decide, or does your application get a value it can recognize as "unknown"?
+
+```ruby
+# config/initializers/firebase_hosting_client_ip.rb
+FirebaseHostingClientIp.configure do |config|
+  # :passthrough (default) - leave Rails' own value alone. Behind Cloud Run
+  #   that is typically a Google front-end address, not your client.
+  # A String - written to request.remote_ip verbatim, so the application can
+  #   detect it and act accordingly (e.g. fail closed on IP-gated actions).
+  config.missing_header_fallback = "0.0.0.0"
+end
+```
+
+Any String is accepted, including `""`; the gem imposes no meaning on the sentinel — that is your application's decision. Non-String values other than `:passthrough` raise `ArgumentError`, because `request.remote_ip` coerces with `to_s` and a `nil` would silently fall back to Rack's own calculation.
+
+If you do anything security-adjacent with `request.remote_ip` — allowlisting, rate limiting, audit trails — prefer a sentinel. Passthrough means a Google address flows into that logic looking exactly like a real client.
+
+### A header is considered valid only if it is a bare host address
+
+These are all treated as if the header were missing:
+
+| Value | Why |
+|---|---|
+| `""`, `"   "` | empty |
+| `"not-an-ip"` | unparseable |
+| `"192.0.2.1/24"`, `"2001:db8::1/64"` | a range is not a client address |
+| `"[2001:db8::42]"` | bracketed form |
+| `"2001:db8::42%eth0"` | zone identifier |
+
+`IPAddr.new` accepts several of these, so the gem rejects them explicitly rather than passing them to Rails, where they would raise in any consumer that parses the value.
+
+## Security
+
+**This middleware trusts an HTTP header, and that header is not cryptographically protected.**
+
+Two separate attacks matter, and blocking one does not block the other:
+
+1. **Direct requests to the origin.** Anyone who can reach your Cloud Run service without going through Firebase Hosting can set `Fastly-Client-IP` to anything. Restrict ingress (internal + load balancer only) so this is not possible. This gem cannot help with it — lock down ingress.
+2. **Requests through Firebase Hosting carrying a forged header.** By Fastly's own documentation, `Fastly-Client-IP` is *not* protected by default: "if a client sets this header themselves, we will use it." Fastly documents a one-line VCL guard that overwrites it with the observed client address, but whether a given customer applies it is that customer's edge configuration, which you do not control or see.
+
+**On Firebase Hosting, the edge overwrites a forged header — observed directly, though still not a documented guarantee.** Tested against a live Firebase-fronted Cloud Run app, by reading the header that arrived at the origin (not just the resolved value):
 
 ```bash
-bundle install
+curl -H 'Fastly-Client-IP: 192.0.2.123' -H 'X-Forwarded-For: 203.0.113.55' \
+     https://your-app.example.com/some-endpoint-that-echoes-headers
 ```
 
-## Requirements
+The `Fastly-Client-IP` that reached the origin was the caller's **real** address, not the forged `192.0.2.123`. The forged `X-Forwarded-For` did survive into Fastly's own `Fastly-Temp-Xff` header — so the edge *saw* it — but `Fastly-Client-IP` is derived from the connection Fastly observed (`client.ip`), not from any client-supplied header, so the forgery could not reach it. This is Fastly's documented guard in effect:
 
-- Ruby >= 3.2.0
-- Rails >= 7.0 (Rails 7, Rails 8, and future versions are supported)
+```vcl
+if (fastly.ff.visits_this_service == 0 && req.restarts == 0) {
+  set req.http.Fastly-Client-IP = client.ip;
+}
+```
 
-The gem automatically works with whatever Rails version is specified in your application's Gemfile.
+That property — computed from the observed connection rather than a forwarded header — is what makes `Fastly-Client-IP` more resistant to spoofing than `X-Forwarded-For` on this path.
 
-## Usage
+Two caveats remain. It is one deployment's behavior, undocumented by Firebase and outside your control, so it could change without notice. And it says nothing about attack 1 — a request that reaches the origin directly never passes through the edge that sets this header. Treat the CDN sanitization as defense-in-depth, not as the thing your security rests on: lock down ingress, **verify against your own deployment, and re-verify periodically** by confirming the `Fastly-Client-IP` that arrives is the caller's real address rather than a forged one.
 
-The middleware is automatically loaded when Rails is detected. No additional configuration is required.
+### Choose based on what you use the IP for
 
-The middleware is inserted into the Rails middleware stack after `ActionDispatch::RemoteIp`, ensuring proper precedence in the request processing chain.
+- **Logging, analytics, geolocation, personalization** — safe to use as-is. Even in the worst case (the edge does not sanitize the header), a wrong IP in a subset of requests beats a Google address in all of them.
+- **IP allowlists, rate limiting, fraud signals, audit records used as evidence** — safe *only* when both hold: origin ingress is locked down (attack 1), and you have verified the edge overwrites a forged `Fastly-Client-IP` (attack 2). If you cannot confirm both, an attacker who can forge the header chooses the allowlist entry they match or the bucket they exhaust.
 
-### Expected Behavior
+Note that `missing_header_fallback` gives no protection here: a forged header is *present and valid*, so it never reaches the fallback path. The gem reports the best available answer; the trustworthiness of that answer comes from the edge, not from the gem.
+
+## What this gem does not cover
+
+**`request.ip`** is Rack-level and derives from `REMOTE_ADDR`, which this gem deliberately leaves intact. Anything that must see the client IP should read `request.remote_ip`. For a Rack-level consumer that only has `env`:
+
+```ruby
+env["action_dispatch.remote_ip"].to_s
+```
 
-After the middleware processes a request, `request.remote_ip` will return the normalized client IP address according to the following precedence:
+**IPv6.** Fastly reports the client's real address, which is frequently IPv6. The gem passes it through untouched. If your application matches against IPv4-only data — allowlists, geo databases, existing audit records — deciding what to do about that is application policy, not something a middleware should guess at.
 
-1. `HTTP_FASTLY_CLIENT_IP` header (if present and not empty)
-2. Left-most value from `HTTP_X_FORWARDED_FOR` header (if present and not empty)
-3. `REMOTE_ADDR` (the direct connection address)
+## Alternative: teach Rails to skip Google's ranges
 
-### Example
+You may not need this gem. Rails already knows how to walk `X-Forwarded-For` — it just doesn't recognize Google's front end as a proxy. Tell it, and it finds the client on its own:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  def index
-    # This will return the correct client IP even behind Firebase Hosting
-    client_ip = request.remote_ip
-    Rails.logger.info "Request from: #{client_ip}"
-  end
-end
+# config/application.rb
+config.action_dispatch.trusted_proxies =
+  ActionDispatch::RemoteIp::TRUSTED_PROXIES + google_ranges
 ```
 
-### Testing the Middleware
+Google publishes the ranges as machine-readable JSON, refreshed daily:
 
-You can verify the middleware is working by checking the `request.remote_ip` value in your controllers or by inspecting the `REMOTE_ADDR` environment variable in your middleware stack.
+| File | Contents |
+|---|---|
+| `https://www.gstatic.com/ipranges/goog.json` | all Google ranges (~145 prefixes) |
+| `https://www.gstatic.com/ipranges/cloud.json` | Google Cloud only (~1100 prefixes) |
 
-## Development
+Each entry is an `ipv4Prefix` or `ipv6Prefix` you can map to `IPAddr`. Verified: with `X-Forwarded-For: 203.0.113.99, 34.96.0.1`, stock Rails returns `34.96.0.1`; adding the front-end range to `trusted_proxies` makes it return `203.0.113.99`.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Three things to weigh before choosing it:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- **It assumes the client is in `X-Forwarded-For` at all.** Whether Firebase Hosting preserves the original client there — rather than only the hop it received — is undocumented. Test your own deployment before depending on it; if the client is absent from the header, no amount of range filtering recovers it.
+- **Trust the narrowest range you can.** Trusting all of `cloud.json` means trusting every Google Cloud customer. Anyone with a GCP VM can then send a request with a forged `X-Forwarded-For`, have their own (trusted) address appended behind it, and be attributed the value they chose. Trusting only the specific front-end ranges avoids that.
+- **The ranges move.** Vendoring the list means it goes stale; fetching it at boot makes startup depend on a network call. Either is a maintenance cost this gem does not have.
 
-## Contributing
+The trade is roughly: this gem reads one header and is done, but depends on Fastly setting it; the `trusted_proxies` route uses only stock Rails, but depends on the client surviving in `X-Forwarded-For` and on you keeping a range list current.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/quintsys/firebase_hosting_client_ip. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/quintsys/firebase_hosting_client_ip/blob/master/CODE_OF_CONDUCT.md).
+### Using both
 
-## License
+They compose, and each covers the other's failure mode. Configure `trusted_proxies` *and* install the gem, leaving `missing_header_fallback` at `:passthrough`:
+
+```
+Fastly-Client-IP present : 198.51.100.7   ← the gem answers
+Fastly-Client-IP absent  : 203.0.113.99   ← Rails finds the client via ranges
+```
+
+The fallback path stops meaning "you get a Google address" and starts meaning "you get the client according to `X-Forwarded-For`". This is the strongest configuration for accuracy, and it costs one `config.action_dispatch.trusted_proxies` line. Note it only works with `:passthrough` — a sentinel would override the improved fallback.
+
+### Which wins, and when that is the wrong choice
+
+The gem takes precedence: it runs after `ActionDispatch::RemoteIp` and replaces whatever Rails computed. That is right for accuracy — a header set by the hop that actually saw the client beats inferring the client by eliminating known infrastructure from a list that changes daily.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+**It is the wrong precedence if you are defending against forgery.** The two approaches do not degrade the same way under attack. Given a request that forges *both* headers:
+
+```
+X-Forwarded-For: 1.2.3.4, 203.0.113.99, 151.101.1.1, 34.96.0.1
+Fastly-Client-IP: 1.2.3.4
+
+trusted_proxies only : 203.0.113.99   ← the real client
+with this gem        : 1.2.3.4        ← the attacker's choice
+```
 
-## Code of Conduct
+`X-Forwarded-For` resists this because every real proxy appends the peer it saw, so the true client always lands to the *right* of anything the client invented, and Rails takes the right-most untrusted entry. A forged prefix is simply skipped. `Fastly-Client-IP` carries no such structure: it is one value, and if the CDN does not overwrite a client-supplied one, it is whatever the client said.
+
+So installing this gem can *reduce* spoof resistance compared with a correctly configured `trusted_proxies` setup. If you use the client IP for access control rather than observability, prefer `trusted_proxies` — trusting both the CDN and Google hops, using Fastly's published list at `https://api.fastly.com/public-ip-list` alongside Google's — and consider not installing this gem at all. The two precedence orders are already available to you: install it, and the header wins; don't, and the `X-Forwarded-For` walk wins. That is why there is no option to invert it.
+
+All of this assumes the client actually survives in `X-Forwarded-For` behind Firebase Hosting, which is undocumented. The `curl` in the [Security](#security) section answers that and the spoofing question in the same request — run it before choosing.
+
+### Why the gem does not do the range filtering itself
+
+Because Rails already does it, and the data is not the gem's to ship. Google republishes those prefixes daily; a gem released monthly cannot track them, so it would either vendor a list that goes stale — silently returning a Google address again, exactly the bug this gem exists to fix — or fetch at boot and make your application's startup depend on a network call. `trusted_proxies` is a first-class Rails setting and the right home for it.
+
+## Upgrading from 0.x
+
+Breaking changes in 1.0:
+
+- **`REMOTE_ADDR` is no longer overwritten.** If you relied on reading the client IP from `REMOTE_ADDR` or `request.ip`, switch to `request.remote_ip`.
+- **The `X-Forwarded-For` fallback is gone.** When `Fastly-Client-IP` is absent, 0.x returned the left-most `X-Forwarded-For` entry — a value that is either Google's infrastructure or attacker-supplied. 1.0 returns Rails' own value, or your configured sentinel.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+bundle exec rubocop
+bundle exec rake        # spec + rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/quintsys/firebase_hosting_client_ip. Contributors are expected to adhere to the [code of conduct](https://github.com/quintsys/firebase_hosting_client_ip/blob/master/CODE_OF_CONDUCT.md).
+
+## License
 
-Everyone interacting in the FirebaseHostingClientIp project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/quintsys/firebase_hosting_client_ip/blob/master/CODE_OF_CONDUCT.md).
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/firebase_hosting_client_ip/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module FirebaseHostingClientIp
+  # Holds the gem's single configuration option.
+  #
+  # missing_header_fallback controls what request.remote_ip returns when the
+  # Fastly-Client-IP header is absent or invalid:
+  #
+  #   :passthrough (default) - leave Rails' own value untouched. Behind
+  #     Firebase Hosting -> Cloud Run this is typically a Google front-end
+  #     address, not the client.
+  #   any String - written to request.remote_ip as-is, so the application can
+  #     recognize "client IP unknown" and act on it (e.g. fail closed). The
+  #     gem imposes no semantics on the sentinel; any String is accepted,
+  #     including "". It must be a String because Request#remote_ip is
+  #     `(get_header("action_dispatch.remote_ip") || ip).to_s` - a nil or
+  #     false env value silently falls through to Rack's calculation.
+  class Configuration
+    PASSTHROUGH = :passthrough
+
+    attr_reader :missing_header_fallback
+
+    def initialize
+      @missing_header_fallback = PASSTHROUGH
+    end
+
+    def missing_header_fallback=(value)
+      unless value == PASSTHROUGH || value.is_a?(String)
+        raise ArgumentError,
+              "missing_header_fallback must be :passthrough or a String, " \
+              "got #{value.inspect}"
+      end
+
+      @missing_header_fallback = value
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_configuration!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/firebase_hosting_client_ip/middleware.rb

@@ -1,48 +1,69 @@
 # frozen_string_literal: true
 
+require "ipaddr"
+
 module FirebaseHostingClientIp
+  # Makes request.remote_ip return the client IP reported by Firebase Hosting.
+  #
+  # Firebase Hosting fronts the application with Fastly, which sets
+  # Fastly-Client-IP to the address of the end user. That header is the only
+  # trustworthy source in this architecture: behind Cloud Run, the values Rails
+  # derives on its own (from X-Forwarded-For) resolve to a Google front-end
+  # address, and are attacker-controlled if the service can be reached directly.
+  #
+  # The middleware runs after ActionDispatch::RemoteIp and replaces the lazy
+  # value that middleware installed at env["action_dispatch.remote_ip"], which
+  # is exactly what ActionDispatch::Request#remote_ip reads. REMOTE_ADDR is
+  # never modified, so request.ip continues to report the real peer address.
+  #
+  # When the header is absent or invalid, behavior is governed by
+  # FirebaseHostingClientIp.config.missing_header_fallback.
   class Middleware
+    REMOTE_IP_KEY = "action_dispatch.remote_ip"
+    HEADER = "HTTP_FASTLY_CLIENT_IP"
+
+    # Characters that make IPAddr accept something which is not a bare client
+    # address. IPAddr.new is more permissive than this contract needs: it
+    # parses CIDR ranges ("192.0.2.1/24"), bracketed IPv6 ("[2001:db8::42]"),
+    # and zone identifiers ("2001:db8::42%eth0"). None of those are values
+    # Rails should hand out as request.remote_ip, so they are rejected before
+    # parsing rather than repaired.
+    DISALLOWED = %r{[/\[\]%]}
+
     def initialize(app)
       @app = app
     end
 
     def call(env)
-      # Extract the normalized client IP using the precedence rules
-      normalized_ip = extract_client_ip(env)
+      ip = validated_fastly_ip(env)
+      fallback = FirebaseHostingClientIp.config.missing_header_fallback
 
-      # Store the normalized IP in the REMOTE_ADDR so that Rails' request.remote_ip
-      # will return it without needing ActionDispatch::RemoteIp to reprocess
-      env["REMOTE_ADDR"] = normalized_ip if normalized_ip
+      if ip
+        env[REMOTE_IP_KEY] = ip
+      elsif fallback != Configuration::PASSTHROUGH
+        env[REMOTE_IP_KEY] = fallback
+      end
 
       @app.call(env)
     end
 
     private
 
-    def extract_client_ip(env)
-      # Precedence:
-      # 1. HTTP_FASTLY_CLIENT_IP (if present and not empty)
-      # 2. Left-most value from HTTP_X_FORWARDED_FOR (if present and not empty)
-      # 3. Fallback to REMOTE_ADDR (already processed by ActionDispatch::RemoteIp)
-
-      extract_fastly_ip(env) || extract_forwarded_for_ip(env) || env["REMOTE_ADDR"]
-    end
-
-    def extract_fastly_ip(env)
-      fastly_ip = env["HTTP_FASTLY_CLIENT_IP"]
-      fastly_ip = fastly_ip.strip if fastly_ip
-      fastly_ip if fastly_ip&.length&.positive?
-    end
-
-    def extract_forwarded_for_ip(env)
-      x_forwarded_for = env["HTTP_X_FORWARDED_FOR"]
-      return nil unless x_forwarded_for&.length&.positive?
+    # Returns the trimmed header value verbatim when it is a single valid host
+    # address, nil otherwise.
+    #
+    # This validates without transforming: IPAddr is used only as a gate, and
+    # the string handed to Rails keeps the header's own spelling rather than a
+    # canonicalized form. Resolving the trusted header is this gem's only
+    # responsibility; imposing an IP canonicalization policy is not.
+    def validated_fastly_ip(env)
+      raw = env[HEADER]&.strip
+      return nil if raw.nil? || raw.empty? || raw.match?(DISALLOWED)
 
-      # X-Forwarded-For can contain multiple IPs separated by commas
-      # The left-most (first) IP is the original client IP
-      ips = x_forwarded_for.split(",").map(&:strip)
-      first_ip = ips.first
-      first_ip if first_ip&.length&.positive?
+      IPAddr.new(raw)
+      raw
+    rescue IPAddr::Error
+      nil
     end
   end
 end

data/lib/firebase_hosting_client_ip/railtie.rb

@@ -4,14 +4,15 @@ require "rails"
 require_relative "middleware"
 
 module FirebaseHostingClientIp
-  # Railtie for automatic middleware insertion in Rails applications.
+  # Inserts the middleware into the Rails middleware stack.
   # Supports Rails 7, Rails 8, and future versions.
   class Railtie < ::Rails::Railtie
     initializer "firebase_hosting_client_ip.insert_middleware",
                 after: "action_dispatch.remote_ip" do |app|
-      # Insert the middleware after ActionDispatch::RemoteIp
-      # This ensures ActionDispatch::RemoteIp has already processed the request
-      # and we can normalize the IP accordingly
+      # Position matters: the middleware must run *after*
+      # ActionDispatch::RemoteIp so it can replace the value that middleware
+      # installs at env["action_dispatch.remote_ip"]. Inserting it earlier
+      # would let RemoteIp overwrite the trusted Fastly value.
       app.middleware.insert_after(
         ActionDispatch::RemoteIp,
         FirebaseHostingClientIp::Middleware

data/lib/firebase_hosting_client_ip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FirebaseHostingClientIp
-  VERSION = "0.3.1"
+  VERSION = "1.0.0"
 end

data/lib/firebase_hosting_client_ip.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "firebase_hosting_client_ip/version"
+require_relative "firebase_hosting_client_ip/configuration"
 require_relative "firebase_hosting_client_ip/middleware"
 
 module FirebaseHostingClientIp
-  class Error < StandardError; end
 end
 
 require_relative "firebase_hosting_client_ip/railtie" if defined?(Rails)

data/sig/firebase_hosting_client_ip.rbs

@@ -1,4 +1,26 @@
 module FirebaseHostingClientIp
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  def self.config: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_configuration!: () -> Configuration
+
+  class Configuration
+    PASSTHROUGH: Symbol
+
+    attr_reader missing_header_fallback: (:passthrough | String)
+    def missing_header_fallback=: ((:passthrough | String) value) -> (:passthrough | String)
+  end
+
+  class Middleware
+    REMOTE_IP_KEY: String
+    HEADER: String
+    DISALLOWED: Regexp
+
+    def initialize: (untyped app) -> void
+    def call: (Hash[String, untyped] env) -> untyped
+
+    private
+    def validated_fastly_ip: (Hash[String, untyped] env) -> String?
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firebase_hosting_client_ip
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Erich N Quintero
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-23 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -24,9 +24,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Provides a Rails middleware that resolves the correct client IP when
-  an application is deployed behind Firebase Hosting, using a heuristic precedence
-  of headers.
+description: Makes request.remote_ip return the client IP reported by Firebase Hosting's
+  Fastly-Client-IP header, the only trustworthy source behind Firebase Hosting. Leaves
+  REMOTE_ADDR intact and never infers the client from X-Forwarded-For.
 email:
 - qbantek@gmail.com
 executables: []
@@ -42,6 +42,7 @@ files:
 - README.md
 - Rakefile
 - lib/firebase_hosting_client_ip.rb
+- lib/firebase_hosting_client_ip/configuration.rb
 - lib/firebase_hosting_client_ip/middleware.rb
 - lib/firebase_hosting_client_ip/railtie.rb
 - lib/firebase_hosting_client_ip/version.rb
@@ -73,5 +74,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Rails middleware to normalize client IP behind Firebase Hosting
+summary: Rails middleware that makes request.remote_ip trust Fastly-Client-IP
 test_files: []