otto 2.7.0 → 2.8.1

data/lib/otto/privacy.rb

@@ -7,6 +7,8 @@ require_relative 'privacy/config'
 require_relative 'privacy/ip_privacy'
 require_relative 'privacy/user_agent_privacy'
 require_relative 'privacy/geo_resolver'
+require_relative 'privacy/asn_resolver'
+require_relative 'privacy/anonymizer_resolver'
 require_relative 'privacy/redacted_fingerprint'
 
 # Otto::Privacy module provides IP address anonymization and privacy features
@@ -21,6 +23,13 @@ require_relative 'privacy/redacted_fingerprint'
 # - Geo-location resolution (country-level only): a configurable trusted header,
 #   built-in CDN provider headers, an optional local MaxMind-format (.mmdb)
 #   database looked up on the masked IP, or a custom resolver
+# - ASN resolution (opt-in, default off): the network operator an address
+#   belongs to, from a local .mmdb looked up on the masked IP. Database-only —
+#   no CDN publishes a client-ASN header worth trusting
+# - Anonymizer classification (opt-in, default off): whether an address is a
+#   known Tor / VPN / proxy / hosting egress, from a local .mmdb. The only
+#   lookup that reads the unmasked address, because anonymizer data lists
+#   individual nodes at /32 — it returns a label, never the address
 # - User agent anonymization (removes version numbers)
 #
 # Privacy is ENABLED BY DEFAULT. To disable:

data/lib/otto/request.rb

@@ -15,6 +15,8 @@ class Otto
   #   def show(req, res)
   #     req.masked_ip      # Privacy-safe masked IP
   #     req.geo_country    # ISO country code
+  #     req.asn            # Network operator, when enabled
+  #     req.anonymizer     # Tor/VPN/proxy label, when enabled
   #     req.check_locale!  # Set locale for request
   #   end
   #
@@ -63,6 +65,10 @@ class Otto
     # If you need the geo country:
     #   req.geo_country  # => 'US' or nil
     #
+    # If you need the opt-in enrichment signals (nil unless enabled):
+    #   req.asn         # => 'AS15169', '**', or nil
+    #   req.anonymizer  # => 'tor', 'none', '**', or nil
+    #
     # If you need the full privacy fingerprint:
     #   req.redacted_fingerprint  # => RedactedFingerprint object or nil
 
@@ -92,6 +98,39 @@ class Otto
       redacted_fingerprint&.country || env['otto.privacy.geo_country']
     end
 
+    # Get the Autonomous System Number of the client's network
+    #
+    # Opt-in: nil unless the operator enabled ASN resolution. '**' means it is
+    # enabled but nothing resolved — distinguishable from "switched off", which
+    # is what makes the three-state contract worth keeping.
+    #
+    # Read straight from env rather than through the fingerprint. The
+    # `fingerprint&.x || env[...]` idiom used above treats any falsey value as
+    # "fall through", which is wrong for a value whose vocabulary is fixed and
+    # whose absence is itself meaningful.
+    #
+    # @return [String, nil] 'AS15169', '**', or nil when disabled
+    # @example
+    #   req.asn  # => 'AS15169'
+    def asn
+      env['otto.privacy.asn']
+    end
+
+    # Get the anonymizing-egress classification for the client address
+    #
+    # Opt-in: nil unless the operator enabled classification. 'none' means the
+    # database was consulted and did not list the address; '**' means no
+    # database answered. Do not collapse the two — 'none' is evidence that the
+    # address is not a known egress, '**' is the absence of any evidence.
+    #
+    # @return [String, nil] 'tor', 'proxy', 'vpn', 'residential_proxy',
+    #   'hosting', 'anonymous', 'none', '**', or nil when disabled
+    # @example
+    #   req.anonymizer  # => 'tor'
+    def anonymizer
+      env['otto.privacy.anonymizer']
+    end
+
     # Get anonymized user agent string
     #
     # Returns user agent with version numbers stripped for privacy.
@@ -241,19 +280,28 @@ class Otto
     #
     # Prefers the canonical decision recorded once by IPPrivacyMiddleware in
     # env['otto.via_trusted_proxy'] — evaluated against the original peer before
-    # REMOTE_ADDR is masked, so it stays correct even after masking. Falls back
-    # to evaluating the current REMOTE_ADDR when the middleware has not run
-    # (standalone request use).
-    #
-    # This is the trusted-proxy *identity* check only and is independent of
-    # count-based depth mode: depth resolves the client IP but never grants
-    # proxy trust for X-Forwarded-Proto.
+    # REMOTE_ADDR is masked, so it stays correct even after masking. The key is
+    # tri-state: written only when proxy trust is configured, so its absence
+    # covers both "middleware not mounted" (standalone request use) and "no
+    # proxy trust configured" — the fallback below answers both by evaluating
+    # the config directly against the current REMOTE_ADDR (an unconfigured
+    # config yields false, matching what the middleware would have implied).
+    #
+    # A peer earns trust two ways (#226): its identity matches a configured
+    # trusted-proxy CIDR (filter mode), or count-based depth mode is active —
+    # configuring a depth asserts the connecting peer is the operator's
+    # (non-enumerable) proxy tier. The fallback mirrors the grant
+    # IPPrivacyMiddleware records so the two paths cannot disagree.
     #
     # @return [Boolean]
     def forwarded_by_trusted_proxy?
       return env['otto.via_trusted_proxy'] if env.key?('otto.via_trusted_proxy')
 
-      otto_security_config ? trusted_proxy?(env['REMOTE_ADDR']) : false
+      config = otto_security_config
+      return false unless config
+      return true if config.trusted_proxy_depth_mode?
+
+      trusted_proxy?(env['REMOTE_ADDR'])
     end
 
     # See: http://stackoverflow.com/questions/10013812/how-to-prevent-jquery-ajax-from-following-a-redirect-after-a-post

data/lib/otto/security/config.rb

@@ -38,6 +38,23 @@ class Otto
         hop count, not both.
       MSG
 
+      # Error raised when an app-configured trusted geo header (ip_privacy
+      # geo_header) is combined with count-based depth mode. Geo headers are
+      # honored only for peers matching enumerated trusted_proxies CIDRs
+      # (geo_headers_trusted? gates on trusted_proxies_configured?) — a hop
+      # trusted by count cannot be verified as the geo-setting CDN — so a
+      # geo_header configured alongside a depth could never be consulted.
+      # Failing loud at config time replaces a silent database/'**' fallback
+      # at request time.
+      GEO_HEADER_DEPTH_CONFLICT_MESSAGE = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        Cannot configure a trusted geo header (ip_privacy geo_header) together
+        with trusted_proxy_depth (count mode): geo headers are only honored
+        for peers matching enumerated trusted_proxies CIDRs, so the header
+        would be silently ignored. Use filter mode (add_trusted_proxy) for
+        header-based geo, or drop geo_header and use database-backed geo
+        (geo_db_path or geo_db_reader).
+      MSG
+
       # Forwarded-header sources depth mode (#trusted_proxy_depth) can count
       # hops from: X-Forwarded-For (default), the RFC 7239 Forwarded header, or
       # Both (Forwarded when present, else X-Forwarded-For). Mirrors
@@ -219,18 +236,30 @@ class Otto
 
       # Whether any trusted-proxy IP/CIDR/Regexp matchers are configured.
       #
-      # This mirrors {#trusted_proxy?}, which consults the same matcher list, so
-      # the two answers stay consistent: a request can only be "via a trusted
-      # proxy" when matchers exist. It deliberately EXCLUDES count-based depth
-      # mode — depth resolves the client IP but never confers proxy identity
-      # trust (the same decoupling {Otto::Request#forwarded_by_trusted_proxy?}
-      # applies to X-Forwarded-Proto). Used to gate geo-header trust.
+      # This mirrors {#trusted_proxy?}, which consults the same matcher list.
+      # It deliberately EXCLUDES count-based depth mode: depth grants the peer
+      # blanket trust for otto.via_trusted_proxy (#226), but it cannot verify
+      # that the hop is a geo-setting CDN, so header-based geo stays gated on
+      # enumerated matchers only. Used to gate geo-header trust.
       #
       # @return [Boolean] true when at least one trusted-proxy matcher exists
       def trusted_proxies_configured?
         @trusted_proxy_matchers.any?
       end
 
+      # Whether ANY proxy-trust mode is configured — CIDR matchers (filter
+      # mode) or count-based depth. This is the gate for writing
+      # env['otto.via_trusted_proxy'] at all: when neither mode is configured
+      # the key is left ABSENT (tri-state contract), so downstream consumers
+      # can distinguish "operator configured trust and this peer failed it"
+      # (false) from "no proxy trust configured" (absent) and apply their own
+      # legacy heuristics only in the latter case.
+      #
+      # @return [Boolean] true when filter or depth mode is configured
+      def proxy_trust_configured?
+        trusted_proxies_configured? || trusted_proxy_depth_mode?
+      end
+
       # Whether count-based ("trust the last N hops") proxy resolution is active.
       #
       # When true, Otto::Utils.resolve_client_ip ignores trusted-proxy CIDRs and
@@ -260,6 +289,9 @@ class Otto
 
         validate_trusted_proxy_depth!(depth)
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if depth.to_i >= 1 && @trusted_proxies.any?
+        # Depth-then-geo assignment order is caught by configure_ip_privacy;
+        # this catches geo-then-depth so both orders fail eagerly.
+        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE if depth.to_i >= 1 && @ip_privacy_config&.geo_header
 
         @trusted_proxy_depth = depth
       end
@@ -763,6 +795,12 @@ class Otto
         return if @trusted_proxy_depth.nil?
 
         raise ArgumentError, PROXY_MODE_CONFLICT_MESSAGE if @trusted_proxy_depth >= 1 && @trusted_proxies.any?
+
+        # Backstop for the direct path (ip_privacy_config.geo_header=) that
+        # bypasses both eager checks; the setters cover the common orders.
+        return unless @trusted_proxy_depth >= 1 && @ip_privacy_config&.geo_header
+
+        raise ArgumentError, GEO_HEADER_DEPTH_CONFLICT_MESSAGE
       end
 
       # Parse a value into an IPAddr, returning nil for invalid / non-IP input.

data/lib/otto/security/csp/policy.rb

@@ -222,15 +222,17 @@ class Otto
 
         # CSP directives for the development environment.
         #
-        # Development mode allows inline scripts/styles and hot reloading
-        # connections for better developer experience with build tools like Vite.
+        # Development mode allows nonce-authorized inline scripts, inline styles,
+        # HTTP(S) scripts, and hot-reloading connections for build tools such as
+        # Vite. HTTP(S) script sources support both same-origin reverse proxies
+        # (for example Caddy) and direct local Vite servers on another port.
         #
         # @param nonce [String] nonce value injected into `script-src`
         # @return [Array<String>] directive strings, each terminated with `;`
         def development_directives(nonce)
           [
             "default-src 'none';",
-            "script-src 'nonce-#{nonce}' 'unsafe-inline';", # Allow inline scripts for development tools
+            "script-src 'self' 'nonce-#{nonce}' http: https:;",
             "style-src 'self' 'unsafe-inline';",
             "connect-src 'self' ws: wss: http: https:;", # Allow HTTP and all WebSocket connections for dev tools
             "img-src 'self' data:;",

data/lib/otto/security/middleware/ip_privacy_middleware.rb

@@ -21,7 +21,9 @@ class Otto
       # 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['otto.via_trusted_proxy'] and env['otto.peer_loopback'].
+      # env['otto.via_trusted_proxy'] (only when proxy trust is configured —
+      # absent otherwise, see the tri-state note in #call) and
+      # env['otto.peer_loopback'].
       #
       # @example Default behavior (privacy enabled)
       #   # env['REMOTE_ADDR'] is masked to 192.168.1.0
@@ -62,11 +64,22 @@ class Otto
           # secure? can authorize X-Forwarded-Proto canonically even after
           # REMOTE_ADDR is rewritten to the masked client IP. Leak-free boolean.
           #
-          # This is the trusted-proxy *identity* check only — it is deliberately
-          # independent of count-based depth mode. Depth resolves the client IP;
-          # it never grants proxy trust for X-Forwarded-Proto (matching the
-          # downstream OneTimeSecret behavior).
-          env['otto.via_trusted_proxy'] = trusted_proxy?(env['REMOTE_ADDR'])
+          # TRI-STATE: the key is written ONLY when the operator configured
+          # proxy trust (CIDR matchers or a depth). 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".
+          if @security_config.respond_to?(:proxy_trust_configured?) && @security_config.proxy_trust_configured?
+            env['otto.via_trusted_proxy'] = trusted_proxy?(env['REMOTE_ADDR'])
+          end
 
           # Same rationale, for loopback: this middleware runs outermost, so a
           # downstream middleware that must authenticate a DIRECT LOCAL CALL
@@ -207,7 +220,8 @@ class Otto
               #
               # This early return also means NONE of the privacy fingerprint
               # values are produced for exempt IPs — no otto.privacy.fingerprint,
-              # masked_ip, hashed_ip, geo_country, or correlation_hash. That is
+              # masked_ip, hashed_ip, geo_country, asn, anonymizer, or
+              # correlation_hash. That is
               # intentional and consistent: the correlation hash targets public
               # audit-trail traffic, so req.ip_correlation_hash is nil for
               # localhost / RFC-1918 addresses (the default dev path) even when a
@@ -238,6 +252,10 @@ class Otto
           env['otto.privacy.masked_ip'] = fingerprint.masked_ip
           env['otto.privacy.hashed_ip'] = fingerprint.hashed_ip
           env['otto.privacy.geo_country'] = fingerprint.country
+          # nil unless the operator opted in; '**' when enabled but
+          # unresolved, so a consumer can tell "off" from "no answer".
+          env['otto.privacy.asn'] = fingerprint.asn
+          env['otto.privacy.anonymizer'] = fingerprint.anonymizer
 
           # Fingerprint the FULL client IP here — while client_ip is still the
           # real address, before REMOTE_ADDR is masked below — so it identifies
@@ -420,12 +438,20 @@ class Otto
           Otto.logger.debug "[IPPrivacyMiddleware] Masked forwarded headers" if Otto.debug
         end
 
-        # Check if an IP is from a trusted proxy
+        # Check if the connecting peer counts as a trusted proxy
+        #
+        # CIDR filter mode checks the peer's identity against the configured
+        # matchers. Count-based depth mode has no enumerable matchers — the
+        # depth setting itself is the operator's assertion that the peer is
+        # their proxy tier — so an active depth grants peer trust outright
+        # (#226). Geo-header trust is unaffected: geo_headers_trusted? gates on
+        # trusted_proxies_configured?, which stays matcher-only.
         #
         # @param ip [String] IP address to check
         # @return [Boolean] true if IP is from a trusted proxy
         def trusted_proxy?(ip)
           return false unless @security_config
+          return true if @security_config.trusted_proxy_depth_mode?
 
           @security_config.trusted_proxy?(ip)
         end

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.7.0'
+  VERSION = '2.8.1'
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.1
 platform: ruby
 authors:
 - Delano Mandelbaum
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -131,6 +132,7 @@ files:
 - ".reek.yml"
 - ".rspec"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".yardopts"
 - AGENTS.md
 - CHANGELOG.rst
@@ -145,6 +147,7 @@ files:
 - docs/.gitignore
 - docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md
 - docs/1108-STREAMING_SUPPORT_SUMMARY.md
+- docs/enrichment.md
 - docs/geo-country.md
 - docs/ipaddr-encoding-quirk.md
 - docs/migrating/v2.0.0-pre1.md
@@ -255,6 +258,8 @@ files:
 - lib/otto/mcp/schema_validation.rb
 - lib/otto/mcp/server.rb
 - lib/otto/privacy.rb
+- lib/otto/privacy/anonymizer_resolver.rb
+- lib/otto/privacy/asn_resolver.rb
 - lib/otto/privacy/config.rb
 - lib/otto/privacy/core.rb
 - lib/otto/privacy/geo_resolver.rb
@@ -329,6 +334,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -346,7 +352,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Define your rack-apps in plaintext.
 test_files: []