tina4ruby 3.13.94 → 3.13.97

data/lib/tina4/rack_app.rb

@@ -19,6 +19,8 @@ module Tina4
   end
 
   class RackApp
+    include Tina4::DispatchPipeline
+
     class << self
       # The process-wide RackApp — the app actually serving traffic. Set by
       # #initialize (last one wins, the same convention as
@@ -78,234 +80,64 @@ module Tina4
       Tina4::Router.websocket("/__dev_reload", &DEV_RELOAD_WS_HANDLER)
     end
 
+    # Run the dispatch pipeline. See REQUEST_STAGES / RESPONSE_STAGES above.
+    #
+    # Every branch this used to hold now lives in a named stage, so the only
+    # control flow left here is "walk the list, stop when a stage answers".
     def call(env)
-      method = env["REQUEST_METHOD"]
-      path = env["PATH_INFO"] || "/"
-      request_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      # Request-scoped query cache boundary (v3.13.23). Tina4 Ruby runs a
-      # long-running Rack server, so the request-scoped DB cache (default-on)
-      # would otherwise serve rows from a previous request. Clear it on every
-      # live connection at the very start of each request, before any routing.
-      # No-op for persistent-mode (TINA4_DB_CACHE=true) connections.
-      Tina4::Database.reset_request_caches if defined?(Tina4::Database)
-
-      # Fast-path: CORS preflight. Real CORS preflight requests carry an
-      # Origin header AND an Access-Control-Request-Method header — the
-      # browser is asking "may I send this method?" before the actual
-      # request. If neither is present, the OPTIONS is a plain protocol-
-      # introspection request (link checker, monitoring probe, RFC 9110
-      # §9.3.7 OPTIONS) and must fall through to the router's generic
-      # Allow-header response. Otherwise we'd shadow the framework's own
-      # OPTIONS support and force every operator to hand-register CORS
-      # exceptions for every introspection client.
-      if method == "OPTIONS" && (env["HTTP_ORIGIN"] || env["HTTP_ACCESS_CONTROL_REQUEST_METHOD"])
-        return Tina4::CorsMiddleware.preflight_response(env)
-      end
-
-      # WebSocket upgrade — match against registered ws_routes
-      if websocket_upgrade?(env)
-        ws_result = Tina4::Router.find_ws_route(path)
-        if ws_result
-          ws_route, ws_params = ws_result
-          return handle_websocket_upgrade(env, ws_route, ws_params)
-        end
+      ctx = DispatchContext.new(
+        env: env,
+        method: env["REQUEST_METHOD"],
+        path: env["PATH_INFO"] || "/",
+        started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+        bypass_response_stages: false
+      )
+
+      response = nil
+      REQUEST_STAGES.each do |stage|
+        response = send(stage, ctx)
+        break if response
       end
 
-      # Dev dashboard routes (handled before anything else)
-      if path.start_with?("/__dev")
-        # Block live-reload endpoint on the AI port — AI tools must get stable responses
-        if path == "/__dev_reload" && env["tina4.ai_port"]
-          return [404, { "content-type" => "text/plain" }, ["Not available on AI port"]]
+      unless ctx.bypass_response_stages
+        RESPONSE_STAGES.each do |stage|
+          replacement = send(stage, ctx, response)
+          response = replacement if replacement
         end
-        dev_response = Tina4::DevAdmin.handle_request(env)
-        return dev_response if dev_response
-      end
-
-      # Customer feedback widget routes (parity with Python's /__feedback/*
-      # surface — see tina4/feedback.rb). Always available — the master
-      # switch (TINA4_ENABLE_FEEDBACK) is enforced INSIDE handle_request
-      # so route shape stays stable across environments.
-      if path.start_with?("/__feedback")
-        fb_response = Tina4::Feedback.handle_request(env)
-        return fb_response if fb_response
       end
 
-      # Fast-path: API routes skip static file + swagger checks entirely
-      unless path.start_with?("/api/")
-        # Swagger
-        if path == "/swagger" || path == "/swagger/"
-          return serve_swagger_ui
-        end
-        if path == "/swagger/openapi.json"
-          return serve_openapi_json
-        end
-
-        # Static files (only for non-API paths)
-        static_response = try_static(path, env)
-        return static_response if static_response
-      end
-
-      # Route matching
-      result = Tina4::Router.match(method, path)
-      if result
-        route, path_params = result
-        rack_response = handle_route(env, route, path_params)
-        matched_pattern = route.path
-      else
-        # RFC 9110 conformance — before falling through to 404, check whether
-        # the PATH is known to the router under any OTHER method.
-        #   - OPTIONS request → 204 with Allow header (§9.3.7). Bare OPTIONS
-        #     on an unknown path also returns 204 (empty Allow header) —
-        #     OPTIONS is a discovery method; rejecting unknown probes with
-        #     404 confuses link checkers and monitoring tools and breaks
-        #     CORS preflight that lacks the Origin/ACRM headers our earlier
-        #     fast-path requires. Matches PHP/Node behaviour. Fixes
-        #     spec/rack_app_spec.rb OPTIONS preflight.
-        #   - Any other method (PUT on GET-only, TRACE, CONNECT, etc.)
-        #     → 405 with Allow header (§15.5.6 + §10.2.1) when the path
-        #     exists; → 404 when nothing about the path is known.
-        allowed = Tina4::Router.methods_allowed_for_path(path)
-        if method.to_s.upcase == "OPTIONS"
-          allow_header = allowed.empty? ? "" : allowed.join(", ")
-          rack_response = [204, { "allow" => allow_header, "content-length" => "0" }, [""]]
-          matched_pattern = nil
-        elsif !allowed.empty?
-          allow_header = allowed.join(", ")
-          body = %({"error":"Method Not Allowed","path":"#{path}","method":"#{method}","allow":[#{allowed.map { |m| %("#{m}") }.join(",")}],"status":405})
-          rack_response = [405, {
-            "allow" => allow_header,
-            "content-type" => "application/json",
-            "content-length" => body.bytesize.to_s
-          }, [body]]
-          matched_pattern = nil
-        else
-          rack_response = handle_404(path)
-          matched_pattern = nil
-        end
-      end
-
-      # RFC 9110 §9.3.2: a HEAD response MUST NOT include content. Strip
-      # the body unconditionally and record what Content-Length the GET
-      # would have sent. Cache validators / link checkers / monitoring
-      # probes use that header to estimate sizes.
-      if method.to_s.upcase == "HEAD"
-        status, headers, body_parts = rack_response
-        joined = body_parts.respond_to?(:join) ? body_parts.join : body_parts.to_s
-        unless joined.empty?
-          new_headers = headers.dup
-          new_headers["content-length"] = joined.bytesize.to_s
-          rack_response = [status, new_headers, [""]]
-        end
-      end
-
-      # Capture request for dev inspector
-      if dev_mode? && !path.start_with?("/__dev")
-        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - request_start) * 1000).round(3)
-        Tina4::DevAdmin.request_inspector.capture(
-          method: method,
-          path: path,
-          status: rack_response[0],
-          duration: duration_ms
-        )
-      end
-
-      # Request log line (v3.13.14). The dev inspector above only feeds the
-      # /__dev UI — it never reached stdout, so `tina4ruby serve` printed the
-      # banner then went silent. Emit a per-request line through Tina4::Log so
-      # it lands on stdout (docker logs / k8s). On by default in dev, opt-in in
-      # production via TINA4_LOG_REQUESTS. Same format across all four frameworks.
-      if request_logging_enabled? && !path.start_with?("/__dev")
-        log_elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - request_start) * 1000).round(3)
-        Tina4::Log.info("#{method} #{path} -> #{rack_response[0]} (#{log_elapsed}ms)")
-      end
-
-      # Inject dev overlay button for HTML responses in dev mode
-      if dev_mode? && !path.start_with?("/__dev")
-        status, headers, body_parts = rack_response
-        content_type = headers["content-type"] || ""
-        if content_type.include?("text/html")
-          request_info = {
-            method: method,
-            path: path,
-            matched_pattern: matched_pattern || "(no match)",
-          }
-          joined = body_parts.join
-          overlay = inject_dev_overlay(joined, request_info, ai_port: env["tina4.ai_port"])
-          rack_response = [status, headers, [overlay]]
-        end
-      end
-
-      # Customer feedback widget injection — runs LAST so its <script>
-      # tag survives any earlier post-processing. No-op if disabled
-      # (TINA4_ENABLE_FEEDBACK off), the user isn't whitelisted, the
-      # path is /__dev or /__feedback, or the body isn't text/html with
-      # a closing </body> tag. Mirrors Python's server.py call site —
-      # see tina4_python/core/server.py around line 1543.
-      begin
-        status, headers, body_parts = rack_response
-        content_type = headers["content-type"] || ""
-        if content_type.include?("text/html") && body_parts.respond_to?(:join)
-          joined = body_parts.join
-          if joined.include?("</body>")
-            injected = Tina4::Feedback.inject_feedback_widget(
-              Struct.new(:path, :env).new(path, env),
-              joined
-            )
-            if injected != joined
-              new_headers = headers.dup
-              new_headers["content-length"] = injected.bytesize.to_s if new_headers["content-length"]
-              rack_response = [status, new_headers, [injected]]
-            end
-          end
-        end
-      rescue StandardError
-        # Injection is best-effort — never break the response.
+      # LAST, and unconditionally. RFC 9110 s9.3.2 applies to EVERY response
+      # however it was produced - the swagger and static branches that skip the
+      # stages above, AND anything those stages added.
+      #
+      # Running it FIRST was wrong twice over: the static branches skipped it
+      # (the bug this group was created to fix), and in dev mode
+      # dev_toolbar_inject then put 8.5KB of markup back into an
+      # already-stripped HEAD response. CI caught the second one because it
+      # sets TINA4_DEBUG; a local run without it did not.
+      #
+      # Running it last also makes Content-Length right: it reports the body
+      # AFTER injection, which is exactly what the equivalent GET would send
+      # (s9.3.2 SHOULD - same headers as the GET).
+      ALWAYS_STAGES.each do |stage|
+        replacement = send(stage, ctx, response)
+        response = replacement if replacement
       end
 
-      # Save session and set cookie if session was used
-      if result && defined?(rack_response)
-        status, headers, body_parts = rack_response
-        request_obj = env["tina4.request"]
-        if request_obj&.instance_variable_get(:@session)
-          sess = request_obj.session
-          sess.save
-
-          # Probabilistic garbage collection (~1% of requests)
-          if rand(1..100) == 1
-            begin
-              sess.gc
-            rescue StandardError
-              # GC failure is non-critical — silently ignore
-            end
-          end
-
-          sid = sess.id
-          # Read the INCOMING session cookie by the SAME configured name the
-          # write side emits — via the one shared resolver (Session.cookie_name),
-          # exact `name=` prefix. A hardcoded "tina4_session=" here never matches
-          # a cookie renamed through TINA4_SESSION_NAME, so the auto-Set-Cookie
-          # would be needlessly re-emitted on every request that already carries
-          # the renamed session cookie. Parity with Python's
-          # core/server._init_session cookie_prefix.
-          cookie_prefix = "#{Tina4::Session.cookie_name}="
-          cookie_val = (env["HTTP_COOKIE"] || "").split(";").map(&:strip)
-                                                 .find { |part| part.start_with?(cookie_prefix) }
-                                                 &.slice(cookie_prefix.length..)
-          if sid && sid != cookie_val
-            # Route through Session#cookie_header rather than hand-writing the
-            # header, so TINA4_SESSION_SECURE / _SAMESITE / _HTTPONLY / _NAME /
-            # _TTL are all honoured and Secure reflects the request scheme. The
-            # old hand-written literal ignored every attribute except TTL and
-            # hardcoded SameSite=Lax + HttpOnly, making the security env vars
-            # silent no-ops (issue #31).
-            headers["set-cookie"] = sess.cookie_header
-          end
-          rack_response = [status, headers, body_parts]
-        end
-      end
-
-      rack_response
+      response
+    rescue Tina4::Request::PayloadTooLarge => e
+      # 413, not 500. PayloadTooLarge was raised by Request and rescued by
+      # nobody, so it fell into the generic handler below and an oversized
+      # upload answered "Internal Server Error" - which tells the caller to
+      # retry the exact request that will fail again.
+      #
+      # Measured on Puma with a 1MB TINA4_MAX_UPLOAD_SIZE and an 8MB body:
+      # HTTP 500, and the same for a chunked body. Memory stayed flat (Puma
+      # bounds the read), so unlike Node and Python this was only ever the
+      # status code - but the status code is what a client acts on.
+      body = JSON.generate({ "error" => e.message })
+      [413, { "content-type" => "application/json",
+              "content-length" => body.bytesize.to_s }, [body]]
     rescue => e
       handle_500(e, env)
     end
@@ -320,99 +152,37 @@ module Tina4
 
     private
 
-    def handle_route(env, route, path_params)
-      # Auth check (legacy per-route auth_handler)
-      if route.auth_handler
-        auth_result = route.auth_handler.call(env)
-        return handle_403(env["PATH_INFO"] || "/") unless auth_result
-      end
-
-      # Secure-by-default: enforce bearer-token auth on write routes.
-      # Extracted into a class method so the in-process TestClient enforces the
-      # EXACT same gate (parity with Python #PY2 — a tokenless write must 401 in
-      # tests too, or a green test hides a live 401 and the verification lies).
-      unauthorized = self.class.enforce_route_auth(env, route)
-      return unauthorized if unauthorized
-
-      request = Tina4::Request.new(env, path_params)
-      request.user = env["tina4.auth_payload"] if env["tina4.auth_payload"]
-      env["tina4.request"] = request  # Store for session save after response
-      response = Tina4::Response.new
-
-      # Run global middleware (block-based + class-based before_* methods).
-      # M2 — AFTER-ON-4xx RULE: when a before_* short-circuits (4xx/skip) or
-      # throws (clean 500), the after-pass STILL runs so after_* can add
-      # headers/logging — consistent across all 4 frameworks.
-      unless Tina4::Middleware.run_before(Tina4::Middleware.global_middleware, request, response)
-        Tina4::Middleware.run_after(Tina4::Middleware.global_middleware, request, response)
-        return response.to_rack
-      end
-
-      # Run per-route middleware
-      if route.respond_to?(:run_middleware)
-        unless route.run_middleware(request, response)
-          return [403, { "content-type" => "text/html" }, ["403 Forbidden"]]
-        end
-      end
-
-      # Build the route-handler call as a lambda so function-style
-      # middleware can wrap it. Path params are still bound by name —
-      # the continuation just forwards the (possibly-mutated)
-      # request/response pair the outer middleware chose to pass in.
-      handler_params = route.handler.parameters.map(&:last)
-      route_params = path_params || {}
-      invoke_handler = lambda do |req, resp|
-        args = handler_params.map do |name|
-          if route_params.key?(name)
-            route_params[name]
-          elsif name == :request || name == :req
-            req
-          else
-            resp
-          end
-        end
-        args.empty? ? route.handler.call : route.handler.call(*args)
-      end
-
-      # Fold any function-style middleware on this route into a
-      # Russian-doll chain wrapping the handler. First declared is the
-      # outermost layer — it receives the request first, calls
-      # next_handler to descend, and runs its "after" code on the way
-      # out. Class-based middleware (before_*/after_*) is handled
-      # separately by run_middleware above and never goes through here.
-      # tina4-book#141 PY-10-01 (cross-framework parity).
-      fn_mws = route.respond_to?(:function_middleware) ? route.function_middleware : []
-      if fn_mws.empty?
-        result = invoke_handler.call(request, response)
-      else
-        chain = invoke_handler
-        fn_mws.reverse_each do |mw|
-          inner = chain
-          chain = lambda { |req, resp| mw.call(req, resp, inner) }
-        end
-        result = chain.call(request, response)
-      end
-
-      # Template rendering: when a template is set and the handler returned a Hash,
-      # render the template with the hash as data and return the HTML response.
-      if route.template && result.is_a?(Hash)
-        html = Tina4::Template.render(route.template, result)
-        response.html(html)
-        return response.to_rack
-      end
-
-      # Skip auto_detect if handler already returned the response object
-      final_response = result.equal?(response) ? result : Tina4::Response.auto_detect(result, response)
-
-      # Run global after middleware (block-based + class-based after_* methods)
-      Tina4::Middleware.run_after(Tina4::Middleware.global_middleware, request, final_response)
-
-      # Inject FreshToken header when body formToken was used for auth
-      if env["tina4.fresh_token"]
-        final_response.add_header("FreshToken", env["tina4.fresh_token"])
+    # Order: POST-MATCH globals -> auth gate -> the route's OWN middleware.
+    #
+    # The globals run BEFORE the gate so a rate limiter can throttle a
+    # brute-force login and an access log records the 401 - neither is possible
+    # if they only run on authenticated requests. That is what every mainstream
+    # framework does: Django ships CsrfViewMiddleware ahead of
+    # AuthenticationMiddleware and enforces auth in a view decorator after all
+    # MIDDLEWARE, Laravel runs the `web` group before the `auth` route
+    # middleware, ASP.NET puts UseAuthorization last before the endpoint. Ruby
+    # and Python ran the gate first; Node and PHP did not. Aligned on the
+    # mainstream answer (ADR-0012).
+    #
+    # The route's OWN middleware stays AFTER the gate, so middleware attached to
+    # a secured route never processes an unauthenticated request.
+    # Run a matched route. See ROUTE_STAGES in DispatchPipeline.
+    #
+    # Was cyclomatic complexity 24 in one 118-line function; the same two-phase
+    # shape as #call, so it gets the same treatment - short-circuit stages
+    # first, then invoke and finalise.
+    def handle_route(env, route, path_params, pre_request = nil, pre_response = nil)
+      ctx = RouteContext.new(
+        env: env, route: route, path_params: path_params,
+        pre_request: pre_request, pre_response: pre_response
+      )
+
+      ROUTE_STAGES.each do |stage|
+        short_circuit = send(stage, ctx)
+        return short_circuit if short_circuit
       end
 
-      final_response.to_rack
+      finalise_route_response(ctx, invoke_route_handler(ctx))
     end
 
     def try_static(path, env = nil)
@@ -1256,7 +1026,11 @@ module Tina4
 
       # Priority 3: Session token (for secured GET routes after login)
       if token.nil?
-        session = Tina4::Session.new(env)
+        # Request path, so the same log-loud-then-degrade policy as
+        # Request#session (ADR-0021): an unreachable session store must not turn
+        # the auth gate into a 500. It degrades to an empty session, which means
+        # no token, which means the ordinary 401 below - a SERVED request.
+        session = Tina4::Session.new(env, degrade_on_backend_failure: true)
         session_token = session.get("token")
         if session_token && !session_token.empty?
           token = session_token
@@ -1264,10 +1038,14 @@ module Tina4
         end
       end
 
-      # API_KEY bypass — matches tina4_python behavior
-      api_key = ENV["TINA4_API_KEY"]
-      if api_key && !api_key.empty? && token == api_key
-        env["tina4.auth_payload"] = { "api_key" => true }
+      # API_KEY bypass — routed through the timing-safe Tina4::Auth.validate_api_key
+      # (OpenSSL.fixed_length_secure_compare), matching tina4_python's _check_auth.
+      # It used to be a plain `token == api_key`, which returns as soon as two
+      # bytes differ — so response timing leaks the key prefix and the key can be
+      # recovered a character at a time. validate_api_key also covers the unset /
+      # blank / wrong-length cases the old guard spelled out by hand.
+      if Tina4::Auth.validate_api_key(token)
+        env["tina4.auth_payload"] = { "_auth" => "api_key" }
       elsif token
         unless Tina4::Auth.valid_token(token)
           return [401, { "content-type" => "application/json" }, [JSON.generate({ error: "Unauthorized" })]]

data/lib/tina4/request.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require "uri"
 require "json"
+require "ipaddr"
 
 module Tina4
   # A Hash subclass that supports indifferent access (both string and symbol keys).
@@ -114,7 +115,7 @@ module Tina4
 
   class Request
     attr_reader :env, :method, :path, :query_string, :content_type,
-                :path_params, :ip
+                :path_params, :ip, :remote_ip
     attr_accessor :user
 
     # Maximum upload size in bytes (default 10 MB). Override via TINA4_MAX_UPLOAD_SIZE env var.
@@ -137,7 +138,10 @@ module Tina4
           "Request body (#{content_length} bytes) exceeds TINA4_MAX_UPLOAD_SIZE (#{TINA4_MAX_UPLOAD_SIZE} bytes)"
       end
 
-      # Client IP with X-Forwarded-For support
+      # Raw socket peer — NEVER honours X-Forwarded-For, so it can be trusted
+      # for security decisions. Resolved BEFORE @ip: the peer decides whether
+      # the forwarding headers may be believed at all.
+      @remote_ip = (env["REMOTE_ADDR"] || "").to_s
       @ip = extract_client_ip
 
       # Lazy-initialized fields (nil = not yet computed)
@@ -206,8 +210,16 @@ module Tina4
       @cookies ||= parse_cookies
     end
 
+    # The session for THIS request.
+    #
+    # degrade_on_backend_failure: this is the live request path, so a storage
+    # handler that cannot be built (an unreachable database, a refused backend
+    # name) is LOGGED and then degraded to an in-memory-only session rather than
+    # unwinding into RackApp's 500 handler and taking the request down with it
+    # (ADR-0021). TINA4_SESSION_STRICT still re-raises. Direct Session.new
+    # callers keep the loud raise - see the guard in Session#initialize.
     def session
-      @session ||= Tina4::Session.new(@env)
+      @session ||= Tina4::Session.new(@env, degrade_on_backend_failure: true)
     end
 
     # Parsed body (JSON -> Hash, form-urlencoded -> Hash, multipart ->
@@ -240,6 +252,20 @@ module Tina4
 
     # Merged params: query + body + path_params (path_params highest priority)
     # Supports both string and symbol key access (indifferent access).
+    # Attach the matched route's path params AFTER construction.
+    #
+    # The request is built BEFORE route matching now, so pre-match middleware
+    # has something to read and mutate. Path params are only known once a route
+    # has matched, so they are set here and the memoised #params is dropped -
+    # without that reset a pre-match middleware that touched #params would
+    # freeze a param-less copy for the handler.
+    def path_params=(value)
+      @path_params = value || {}
+      @params = nil
+    end
+
+    attr_reader :path_params
+
     def params
       @params ||= build_params
     end
@@ -275,15 +301,29 @@ module Tina4
 
     private
 
+    # Resolve the client IP, honouring forwarding headers ONLY behind a trusted
+    # proxy. X-Forwarded-For is set by whoever sends it, so an unfiltered read
+    # lets any client choose its own rate-limit bucket - and choose SOMEONE
+    # ELSE'S. See ADR-0019.
+    #
+    # Within the chain the RIGHTMOST entry that is not itself a trusted proxy
+    # wins. Taking the leftmost would be no safer than trusting the header
+    # outright: a client can prepend its own hop, and the proxy appends rather
+    # than replaces. This is the algorithm Rack uses (Rack::Request#ip).
     def extract_client_ip
-      # Check X-Forwarded-For first (proxy/load balancer)
+      peer = @remote_ip.to_s
+      return peer.empty? ? "127.0.0.1" : peer unless Tina4.trusted_proxy?(peer)
+
       forwarded = @env["HTTP_X_FORWARDED_FOR"]
       if forwarded && !forwarded.empty?
-        # Take the first (original client) IP
-        forwarded.split(",").first.strip
-      else
-        @env["HTTP_X_REAL_IP"] || @env["REMOTE_ADDR"] || "127.0.0.1"
+        hops = forwarded.split(",").map(&:strip).reject(&:empty?)
+        client = hops.reverse.find { |hop| !Tina4.trusted_proxy?(hop) }
+        # Every hop is itself a trusted proxy - the peer is the best we have.
+        return client || peer
       end
+
+      real_ip = @env["HTTP_X_REAL_IP"].to_s.strip
+      real_ip.empty? ? peer : real_ip
     end
 
     def extract_headers

data/lib/tina4/response.rb

@@ -156,9 +156,50 @@ module Tina4
       self
     end
 
-    def file(path, content_type: nil, download: false)
+    def file(path, content_type: nil, download: false, root: nil)
+      # SECURITY: confine the read. The natural spelling of a download route,
+      #
+      #     response.file("downloads/" + name)   # name = "../secret.env"
+      #
+      # used to serve any file the process could read - measured at 200 with
+      # the contents of a .env one directory above the intended one.
+      #
+      # TWO checks. Containment ALONE does not close it: that payload lands on
+      # <project>/secret.env, which IS inside the project root, and the project
+      # root is exactly where .env lives. Rejecting ".." on the way in is the
+      # check that closes it; containment then catches absolute paths and
+      # symlinks, neither of which carries a ".." segment.
+      # Containment ONLY when a root is declared; defaulting to Dir.pwd broke
+      # every legitimate absolute path.
+      base = root ? ::File.expand_path(root) : nil
+      forbidden = path.to_s.split(%r{[\\/]}).include?("..")
+
+      unless forbidden
+        candidate = (base.nil? || ::File.absolute_path?(path.to_s)) ? path.to_s : ::File.join(base, path.to_s)
+        resolved =
+          begin
+            ::File.realpath(candidate)
+          rescue Errno::ENOENT, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EACCES
+            nil
+          end
+        if resolved && base && base != ::File::SEPARATOR &&
+           resolved != base && !resolved.start_with?(base + ::File::SEPARATOR)
+          forbidden = true
+        end
+        path = resolved || candidate
+      end
+
+      if forbidden
+        # Refuse BEFORE reading: never load bytes we will not send.
+        @status_code = 403
+        @headers["content-type"] = "text/plain"
+        @body = "Forbidden"
+        return self
+      end
+
       unless ::File.exist?(path)
         @status_code = 404
+        @headers["content-type"] = "text/plain"
         @body = "File not found"
         return self
       end