Class: Otto::Security::Middleware::IPPrivacyMiddleware

Inherits:
Object
  • Object
show all
Defined in:
lib/otto/security/middleware/ip_privacy_middleware.rb

Overview

IP Privacy Middleware

Automatically masks IP addresses for privacy by default. Original IPs are never stored unless privacy is explicitly disabled.

Otto pins this middleware to the OUTERMOST position of the stack (the :entrypoint tier — see Otto::Core::MiddlewareStack#add_with_position), so it is the first middleware to touch a request and every other middleware, plus the application, reads masked IPs by default. Before #219 it was registered position: :first, which is first-in-array and therefore INNERMOST: only the wrapped app saw masked values while every other middleware still saw the raw peer address.

Because it now runs ahead of everything, facts about the ORIGINAL peer that downstream code can no longer derive from the (masked) REMOTE_ADDR are recorded first, as leak-free booleans — never as addresses: env (only when proxy trust is configured — absent otherwise, see the tri-state note in #call) and env.

Examples:

Default behavior (privacy enabled)

# env['REMOTE_ADDR'] is masked to 192.168.1.0
# env['otto.privacy.fingerprint'] contains full anonymized data
# env['otto.original_ip'] is NOT set

Privacy disabled

otto.disable_ip_privacy!
# env['REMOTE_ADDR'] contains real IP
# env['otto.original_ip'] also contains real IP

Constant Summary collapse

UNTRUSTED_FORWARDING_METADATA_HEADERS =

Forwarding metadata Rack::Request reads without consulting Otto's proxy trust verdict: host (#host/#authority), scheme (#scheme/#ssl?), and port (#port), from both the X-Forwarded-* family and RFC 7239 Forwarded (host=, proto=, and the port inside for=). Defined in Otto::Utils so Otto::Utils::RELAY_MARKER_HEADERS is built from the same list and cannot fall out of step with what is scrubbed here.

Otto::Utils::FORWARDED_AUTHORITY_HEADERS

Instance Method Summary collapse

Constructor Details

#initialize(app, security_config = nil) ⇒ IPPrivacyMiddleware

Initialize IP Privacy middleware

Parameters:



51
52
53
54
55
 
# File 'lib/otto/security/middleware/ip_privacy_middleware.rb', line 51

def initialize(app, security_config = nil)
  @app = app
  @security_config = security_config
  @config = security_config&.ip_privacy_config || Otto::Privacy::Config.new
end

Instance Method Details

#call(env) ⇒ Array

Process request with IP privacy

Parameters:

  • env (Hash) —

    Rack environment

Returns:

  • (Array) —

    Rack response tuple [status, headers, body]



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/otto/security/middleware/ip_privacy_middleware.rb', line 61

def call(env)
  # Idempotency: if a prior IPPrivacyMiddleware pass already resolved the
  # canonical client IP for this request, do not re-resolve or re-mask.
  # This makes stacking two instances (e.g. an app-level mount plus
  # Otto's built-in router mount) order-safe instead of double-masking.
  #
  # Client-IP resolution is idempotent, but proxy TRUST is not: the
  # prior pass may have run under a different (or no) configuration,
  # so this instance still enforces its own trust posture below.
  if env.key?('otto.client_ip')
    ensure_ip_match_present(env)
    enforce_proxy_trust_after_prior_pass(env)
    return @app.call(env)
  end

  # Record the connecting peer's trust decision BEFORE any masking, so
  # secure? can authorize X-Forwarded-Proto canonically even after
  # REMOTE_ADDR is rewritten to the masked client IP. Leak-free boolean.
  #
  # TRI-STATE: the key is written ONLY when the operator configured
  # proxy trust (CIDR matchers, a depth, or the explicit trust-nobody
  # assertion `trusted_proxies: :none`, which makes the value false for
  # every peer, #259). Present, its value is
  # authoritative in both directions — true means the peer matched a
  # CIDR (filter mode) or depth mode is active (configuring a depth
  # asserts the connecting peer IS the operator's proxy tier, #226);
  # false means trust IS configured and this peer failed it. Absent
  # means no proxy trust is configured at all, so downstream consumers
  # may fall back to their own heuristics without this key vetoing
  # them. Writing false on unconfigured deployments made false
  # ambiguous between "untrusted peer" and "nothing configured", which
  # forced consumers into grant-only reads (#228).
  # respond_to?: like geo_headers_trusted?, a partial/duck-typed
  # config (or nil) that cannot report trust state is "unconfigured".
  proxy_trust_configured = @security_config.respond_to?(:proxy_trust_configured?) &&
                           @security_config.proxy_trust_configured?
  via_trusted_proxy = proxy_trust_configured && trusted_proxy?(env['REMOTE_ADDR'])
  env['otto.via_trusted_proxy'] = via_trusted_proxy if proxy_trust_configured

  # Record whether the request was relayed BEFORE the scrub below can
  # delete the relay markers. Downstream middleware that must
  # authenticate a direct local call (Otto::CaddyTLS::LocalhostGuard)
  # runs after this one and would otherwise read a request whose
  # HTTP_FORWARDED was deleted here as "direct". Leak-free boolean.
  env['otto.peer_relayed'] = Otto::Utils.relayed_request?(env)

  # A peer that failed configured proxy trust cannot supply forwarded
  # host, scheme, or port either. Unconfigured trust (absent tri-state
  # key) is left alone: the operator has asserted nothing, and the
  # contract reserves that state for downstream heuristics (#228), so
  # Rack keeps its own defaults there.
  scrub_untrusted_forwarding_metadata(env) if proxy_trust_configured && !via_trusted_proxy

  # Same rationale, for loopback: this middleware runs outermost, so a
  # downstream middleware that must authenticate a DIRECT LOCAL CALL
  # (Otto::CaddyTLS::LocalhostGuard) can no longer read the true socket
  # peer from REMOTE_ADDR. Record the verdict here, on the untouched
  # peer, as a boolean — the address itself is never exposed.
  #
  # Deliberately the raw peer, NOT the resolved client IP: resolution
  # honors forwarded headers from trusted proxies, and a co-located
  # reverse proxy on loopback is itself a natural trusted proxy, so
  # resolving first would let `X-Forwarded-For: 127.0.0.1` promote a
  # remote caller to "localhost".
  env['otto.peer_loopback'] = Otto::Utils.loopback_address?(env['REMOTE_ADDR'])

  if privacy_enabled?
    apply_privacy(env)
  else
    apply_no_privacy(env)
  end

  @app.call(env)
end