header_guard 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea2dc2323334a13252e61e46ada4dbc84657d0a0f998ee5b1d4481d7c10c0a1b
-  data.tar.gz: 840fa96c9bb743cd59c4aea1a92adf80c116ccb6615af5c9f4d1a34ea3c16b6e
+  metadata.gz: 9fde99ae71b2986c94287ef5b903ba52d00405019346f9c2f61a88c5c81dd24e
+  data.tar.gz: c7af2219fc4d05c19c2923184515921cc91f37e0cbbdb69ef65ae4d0b778c668
 SHA512:
-  metadata.gz: 37cd5fd01fc7d57b0ad5ee1282115f5253552dcb93b9026bf78b8890b75d83d9781a3c85c821e37556432b94a2a9a36dda00eff1061582a51f12855e6b31c908
-  data.tar.gz: 18e56009b28987ccfcdbb78646d07fdf13f0ab9389c02e1d985aef41ec615f020c4012e4d01d3a69de8c48637e6b0de8e7b5ccdae81df15b9573f98b448864b0
+  metadata.gz: 74bb808854cc17a68c1a48d7c424e7e177dd30dcbbe4ae9ecfe5f5fa446475377c443a70a57529bc3a9e5d37dddcb2d39f3008a6da75bf5ddff6f5d6ebf3ee43
+  data.tar.gz: 226cbb1dd847db813eb69c236c59591440f31906683f8e644f1d3dd076e908aeda2c551abae859befd86b8b5909cd05946fa9530c9b0a33dd908efc18616f5b5

data/CHANGELOG.md

@@ -7,7 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-See `PLAN.md` for the remaining remediation work (P3–P5), targeted at 0.3.0.
+See `PLAN.md` for the remaining work (P4–P5).
+
+## [0.3.0] - 2026-09-12
+
+### Added
+
+- **Option validation.** Every option is checked at construction and raises `ArgumentError`
+  with a specific message. Previously an unrecognised Symbol key became a header name
+  verbatim, so `report_onlyy: true` emitted a junk `report_onlyy` header and silently
+  *enforced* a CSP the user meant only to report on. Now rejected: unknown Symbol options;
+  header names that are not valid HTTP tokens; `Content-Security-Policy` or its
+  `-Report-Only` variant given as a raw header (use the option); values that are not a
+  `String`; empty values; `report_only` / `html_only` values that are not `true` or `false`.
+
+- **Control characters in header values are rejected.** A header value or CSP containing
+  CR, LF, NUL or any other control character raises at startup. A CR/LF in a value built
+  from configuration (a `report-uri` from an environment variable, say) would otherwise
+  let it inject further headers or split the response.
+
+- **Removing a default header.** Set a header to `nil` (or `false`) and HeaderGuard stops
+  managing it: the default is not injected and any value the application sets itself
+  passes through untouched. Previously there was no way to opt out of a default; the README
+  suggested `""`, which emitted a malformed empty header.
+
+- **Disabling the CSP.** `content_security_policy: false` stops HeaderGuard sending a CSP,
+  for applications that build one elsewhere (the Rails `content_security_policy` DSL, for
+  example) and want HeaderGuard for the other headers only. `content_security_policy: nil`
+  deliberately keeps the *default* policy, so an unset environment variable cannot silently
+  drop the CSP.
+
+- **Per-path overrides.** `path_overrides: { matcher => options }` scopes a different
+  policy to particular routes — an identity provider's popup page that must keep
+  `window.opener`, an embeddable widget that other sites frame, a legacy page that still
+  needs inline scripts — without relaxing anything site-wide. A `Regexp` key is matched
+  against the request path; a `String` key must match exactly. First match wins. The value
+  is an options hash of the same shape as the top level (headers, `content_security_policy:`,
+  `report_only:`, `html_only:`), layered on top of the global configuration.
+  `Strict-Transport-Security` is refused inside an override: HSTS is host-scoped, not
+  per-document, so a weaker value on one path would apply to the whole site.
+
+### Upgrading from 0.2.x
+
+- Configurations that were accepted but wrong now fail at startup. If HeaderGuard raises
+  `ArgumentError` on boot, the message names the offending option. The common cases: a
+  misspelled Symbol option, and `"Strict-Transport-Security" => ""` from the old README
+  advice — replace with `nil`.
 
 ## [0.2.0] - 2026-09-12
 
@@ -158,7 +203,8 @@ applications will need to opt back into behaviour they relied on.
   `X-Frame-Options`, `Referrer-Policy` and a configurable Content Security Policy,
   with `report_only` support.
 
-[Unreleased]: https://github.com/danielefrisanco/headerguard/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/danielefrisanco/headerguard/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/danielefrisanco/headerguard/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/danielefrisanco/headerguard/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/danielefrisanco/headerguard/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/danielefrisanco/headerguard/compare/v0.1.0...v0.1.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    header_guard (0.2.0)
+    header_guard (0.3.0)
       rack (~> 3.0)
 
 GEM

data/README.md

@@ -60,12 +60,14 @@ If you only want to relax one or two headers (like HSTS) but keep the others, yo
 header_options = {}
 
 if Rails.env.development? || Rails.env.test?
-  # 1. Disable Strict-Transport-Security for local HTTP development
-  header_options["Strict-Transport-Security"] = ""
+  # 1. Don't send Strict-Transport-Security for local HTTP development.
+  #    nil means "HeaderGuard does not manage this header". (An empty string
+  #    is rejected: it would send a malformed header.)
+  header_options["Strict-Transport-Security"] = nil
   
-  # 2. Relax CSP to allow development tools that rely on 'unsafe-inline' scripts/styles
-  # NOTE: The HeaderGuard default CSP uses 'script-src "self"'. This adds the required dev overrides.
-  dev_csp = "script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline';"
+  # 2. Relax CSP to allow development tools that rely on 'unsafe-inline' scripts/styles.
+  #    This replaces the whole default policy, so include every directive you still want.
+  dev_csp = "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; object-src 'none'; frame-ancestors 'none'"
   header_options[:content_security_policy] = dev_csp
 end
 
@@ -172,12 +174,71 @@ config.middleware.use HeaderGuard::Middleware, html_only: true
 ```
 This is a migration aid, not a recommended configuration: it leaves JSON responses without `X-Content-Type-Options`, redirects without HSTS, and error pages without a CSP.
 
+#### 5\. Removing a Default Header
+
+Set a header to `nil` (or `false`) and HeaderGuard stops managing it: the default is not injected, and any value your application sets itself passes through untouched.
+
+```ruby
+# Don't send X-Frame-Options; the app sets its own where it needs one.
+config.middleware.use HeaderGuard::Middleware, "X-Frame-Options" => nil
+
+```
+
+To stop HeaderGuard sending a CSP at all — for example because your application builds one elsewhere, such as with the Rails `content_security_policy` DSL — pass `false`:
+
+```ruby
+# HeaderGuard manages every header except the CSP.
+config.middleware.use HeaderGuard::Middleware, content_security_policy: false
+
+```
+
+Note that `content_security_policy: nil` keeps the **default** policy rather than disabling it, so an unset environment variable (`content_security_policy: ENV["CSP"]`) cannot silently drop your CSP. Only an explicit `false` turns it off.
+
+#### 6\. Per-Path Overrides
+
+Some routes legitimately need a different policy from the rest of the site: an OAuth callback page that must keep `window.opener`, a widget that other sites embed in a frame, a legacy admin page that still needs inline scripts. Rather than relaxing a header site-wide for the sake of one route, scope the change to that route:
+
+```ruby
+config.middleware.use HeaderGuard::Middleware,
+  path_overrides: {
+    # You are the identity provider: the popup page the client opens must keep window.opener.
+    %r{\A/oauth/authorize\z} => { "Cross-Origin-Opener-Policy" => "unsafe-none" },
+
+    # An embeddable widget: framed by other sites, its assets loaded cross-origin.
+    %r{\A/embed/} => {
+      "X-Frame-Options"              => nil,
+      "Cross-Origin-Resource-Policy" => "cross-origin",
+      content_security_policy:          "default-src 'self'; frame-ancestors *"
+    },
+
+    # Trial a stricter policy on one page before rolling it out.
+    "/checkout" => { content_security_policy: "default-src 'none'; script-src 'self'", report_only: true }
+  }
+
+```
+
+- A **`Regexp`** key is matched against the request path; a **`String`** key must match the path exactly (it is not a prefix — use a `Regexp` for prefixes). The first matching entry wins.
+- The value is an options hash with the same shape as the top level: header overrides, `content_security_policy:`, `report_only:`, `html_only:`. It is layered **on top of** your global configuration, so a path inherits everything it doesn't mention.
+- **`Strict-Transport-Security` cannot be overridden per path** and HeaderGuard will refuse to start if you try. HSTS is host-scoped, not per-document: a weaker value sent on one path would update the browser's policy for the entire site.
+
+Anchor your patterns (`\A`, `\z`). `%r{/auth}` also matches `/authors`.
+
+#### 7\. Validation
+
+Every option is checked when the middleware is constructed, and HeaderGuard raises `ArgumentError` with a specific message rather than starting with a weakened policy:
+
+- an unrecognised Symbol option (`reprot_only: true` used to emit a junk header and silently *enforce* the CSP it was meant to only report on);
+- a header name that isn't a valid HTTP token, or that names the CSP (use `content_security_policy:` instead);
+- a header value or CSP that isn't a `String`, is empty, or contains a control character — a CR/LF would let a value injected from configuration split the response;
+- `report_only` / `html_only` values that aren't `true` or `false`;
+- `Strict-Transport-Security` inside a path override.
+
 How It Works
 ------------
 
 HeaderGuard hooks into the Rack request lifecycle and, on every response passing through it:
 
-1.  **Header Merging:** It takes the default security headers and merges them with any custom headers supplied during initialization, ensuring user configuration takes precedence.
+1.  **Header Merging:** At startup it validates your options, then merges any custom headers over the defaults, ensuring user configuration takes precedence. Per-path overrides are layered over that once more. On each request it picks the policy for the request path.
     
 2.  **Standard Header Injection:** It injects every header in the table above (HSTS, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, the cross-origin isolation headers and `Permissions-Policy`) on **every** response, regardless of status code or content type. HSTS matters most on the HTTP→HTTPS redirect, and `nosniff` exists precisely to protect non-HTML bodies such as JSON.
     

data/lib/header_guard/middleware.rb

@@ -11,57 +11,79 @@ module HeaderGuard
   # Which responses receive which headers:
   #
   # * The standard headers (HSTS, X-Content-Type-Options, X-Frame-Options,
-  #   Referrer-Policy) are applied to every response, regardless of status or
-  #   content type. HSTS matters most on the HTTP->HTTPS redirect, and nosniff
-  #   exists precisely to protect non-HTML bodies such as JSON.
+  #   Referrer-Policy, ...) are applied to every response, regardless of status
+  #   or content type. HSTS matters most on the HTTP->HTTPS redirect, and
+  #   nosniff exists precisely to protect non-HTML bodies such as JSON.
   # * The Content Security Policy governs a document, so it is applied only to
   #   HTML responses -- but on every status. Error pages reflect user input and
   #   are a classic XSS surface, so they need a policy at least as much as a
   #   200 does.
   #
-  # Passing `html_only: true` restores the 0.1.x behaviour, where nothing was
-  # injected unless the response was a 2xx with an HTML content type.
+  # Options are validated at construction and raise ArgumentError on anything
+  # unrecognised or malformed, so a typo cannot silently weaken the policy.
   class Middleware
     # Content types treated as HTML documents for the purpose of applying CSP.
     HTML_CONTENT_TYPES = ["text/html", "application/xhtml+xml"].freeze
 
+    # Symbol keys with special meaning. Every other key must be a String naming
+    # a header; any other Symbol is a typo and is rejected.
+    OPTION_KEYS = %i[content_security_policy report_only html_only path_overrides].freeze
+
+    # Headers set through their own option rather than as a raw header, so the
+    # two mechanisms cannot silently fight over the same response header.
+    RESERVED_HEADERS = ["content-security-policy", "content-security-policy-report-only"].freeze
+
+    # Headers whose effect is host-wide rather than per-document. Sending a
+    # weaker value on one path would weaken it for the whole site, so they may
+    # not appear in path_overrides.
+    HOST_SCOPED_HEADERS = ["strict-transport-security"].freeze
+
+    # The RFC 7230 token alphabet: the only characters legal in a header name.
+    HEADER_NAME = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/.freeze
+
+    # Any control character in a header value is rejected. CR and LF in
+    # particular would let a value inject further headers or a whole second
+    # response (response splitting).
+    CONTROL_CHARS = /[\x00-\x1F\x7F]/.freeze
+
+    CSP_HEADER = "content-security-policy"
+    CSP_REPORT_ONLY_HEADER = "content-security-policy-report-only"
+
+    # Fully resolved configuration for one scope: the whole site, or one path.
+    # `csp_value` is nil when CSP is disabled for the scope.
+    Policy = Struct.new(:headers, :csp_key, :csp_value, :html_only, keyword_init: true)
+
     # Initializes the middleware. It merges user-defined options over defaults.
     #
     # @param app [Object] The next application in the Rack stack.
     # @param options [Hash] Configuration options for headers and CSP.
+    # @raise [ArgumentError] on any unknown option, malformed header name or
+    #   value, or a path override that would weaken a host-scoped header.
     def initialize(app, options = {})
       @app = app
 
-      # Use a copy of options for configuration extraction
-      config = options.dup
-
-      # Extract special configuration settings
-      custom_csp = config.delete(:content_security_policy)
-      @report_only = config.delete(:report_only) || false
-      @html_only = config.delete(:html_only) || false
+      raise ArgumentError, "HeaderGuard options must be a Hash, got #{options.class}" unless options.is_a?(Hash)
 
-      # 1. Start with DEFAULT_HEADERS (from header_guard.rb)
-      # 2. Merge remaining options (which are custom headers) over the defaults,
-      #    so the user's header values take precedence.
-      # 3. Normalize every key to lowercase, so a custom "X-Frame-Options"
-      #    overrides the default rather than being emitted alongside it.
-      @headers = DEFAULT_HEADERS.merge(config).each_with_object({}) do |(key, value), normalized|
-        normalized[normalize_key(key)] = value
-      end.freeze
+      defaults = Policy.new(
+        headers: normalize_keys(DEFAULT_HEADERS),
+        csp_key: CSP_HEADER,
+        csp_value: DEFAULT_CSP,
+        html_only: false
+      )
 
-      # Set the final CSP value and the header key based on report_only setting
-      @csp_value = custom_csp || DEFAULT_CSP
-      @csp_header_key = @report_only ? "content-security-policy-report-only" : "content-security-policy"
+      @policy = build_policy(options, defaults, path: nil)
+      @path_policies = build_path_policies(options[:path_overrides])
     end
 
     # The Rack application call method.
     def call(env)
       status, headers, body = @app.call(env)
 
+      policy = policy_for(env["PATH_INFO"])
       html = html?(headers)
 
-      if apply_standard_headers?(status, html)
-        @headers.each do |key, value|
+      if apply_standard_headers?(policy, status, html)
+        policy.headers.each do |key, value|
           # We use assignment here, not `||=`, to ensure the middleware
           # overwrites any headers set by the application before it,
           # adhering to the strong security posture.
@@ -69,26 +91,170 @@ module HeaderGuard
         end
       end
 
-      assign(headers, @csp_header_key, @csp_value) if apply_csp?(status, html)
+      assign(headers, policy.csp_key, policy.csp_value) if policy.csp_value && apply_csp?(policy, status, html)
 
       [status, headers, body]
     end
 
     private
 
+    # ------------------------------------------------------------------
+    # Configuration
+    # ------------------------------------------------------------------
+
+    # Layers one options Hash over a base Policy. Used once for the global
+    # options over the defaults, and once per path override over the global
+    # policy, so an override inherits everything it does not mention.
+    def build_policy(options, base, path:)
+      headers = base.headers.dup
+      csp_value = base.csp_value
+      report_only = base.csp_key == CSP_REPORT_ONLY_HEADER
+      html_only = base.html_only
+
+      options.each do |key, value|
+        case key
+        when :content_security_policy
+          csp_value = resolve_csp(value, csp_value)
+        when :report_only
+          report_only = resolve_flag(key, value, report_only)
+        when :html_only
+          html_only = resolve_flag(key, value, html_only)
+        when :path_overrides
+          raise ArgumentError, "path_overrides cannot be nested inside the override for #{path.inspect}" if path
+        when String
+          name = validate_header_name(key, path)
+          if value.nil? || value == false
+            headers.delete(name)
+          else
+            headers[name] = validate_header_value(key, value)
+          end
+        else
+          raise ArgumentError,
+                "unknown HeaderGuard option #{key.inspect}. Recognised options are " \
+                "#{OPTION_KEYS.map(&:inspect).join(', ')}; custom headers must be given as String keys."
+        end
+      end
+
+      Policy.new(
+        headers: headers.freeze,
+        csp_key: report_only ? CSP_REPORT_ONLY_HEADER : CSP_HEADER,
+        csp_value: csp_value,
+        html_only: html_only
+      )
+    end
+
+    def build_path_policies(overrides)
+      return [].freeze if overrides.nil?
+
+      unless overrides.is_a?(Hash)
+        raise ArgumentError, "path_overrides must be a Hash of path matcher => options, got #{overrides.class}"
+      end
+
+      overrides.map do |matcher, options|
+        unless matcher.is_a?(String) || matcher.is_a?(Regexp)
+          raise ArgumentError, "path_overrides keys must be a String (exact path) or a Regexp, got #{matcher.inspect}"
+        end
+        unless options.is_a?(Hash)
+          raise ArgumentError, "path_overrides[#{matcher.inspect}] must be an options Hash, got #{options.class}"
+        end
+
+        [matcher, build_policy(options, @policy, path: matcher)]
+      end.freeze
+    end
+
+    # nil keeps the inherited value (so an unset ENV var cannot silently
+    # disable CSP); false disables CSP for the scope; a String replaces it.
+    def resolve_csp(value, current)
+      case value
+      when nil then current
+      when false then nil
+      when String then validate_header_value(:content_security_policy, value)
+      else
+        raise ArgumentError, "content_security_policy must be a String, false, or nil, got #{value.inspect}"
+      end
+    end
+
+    def resolve_flag(key, value, current)
+      return current if value.nil?
+      return value if value == true || value == false
+
+      raise ArgumentError, "#{key} must be true or false, got #{value.inspect}"
+    end
+
+    def validate_header_name(key, path)
+      raise ArgumentError, "#{key.inspect} is not a valid HTTP header name" unless key.match?(HEADER_NAME)
+
+      name = key.downcase
+
+      if RESERVED_HEADERS.include?(name)
+        raise ArgumentError,
+              "#{key} cannot be set as a raw header; use the content_security_policy: and report_only: options"
+      end
+
+      if path && HOST_SCOPED_HEADERS.include?(name)
+        raise ArgumentError,
+              "#{key} cannot be overridden for #{path.inspect}: it is host-scoped, not per-document, " \
+              "so a value sent on one path would apply to the whole site"
+      end
+
+      name
+    end
+
+    def validate_header_value(key, value)
+      unless value.is_a?(String)
+        raise ArgumentError, "value for #{key.inspect} must be a String, got #{value.inspect}"
+      end
+      if value.empty?
+        raise ArgumentError, "value for #{key.inspect} is empty; pass nil to remove the header instead"
+      end
+      if value.match?(CONTROL_CHARS)
+        raise ArgumentError,
+              "value for #{key.inspect} contains a control character (CR, LF, ...), which would allow " \
+              "header injection or response splitting"
+      end
+
+      value
+    end
+
+    def normalize_keys(headers)
+      headers.each_with_object({}) do |(key, value), normalized|
+        normalized[normalize_key(key)] = value
+      end
+    end
+
+    def normalize_key(key)
+      key.to_s.downcase
+    end
+
+    # ------------------------------------------------------------------
+    # Per-request
+    # ------------------------------------------------------------------
+
+    # First matching override wins; none matching means the global policy.
+    def policy_for(path)
+      path = path.to_s
+
+      @path_policies.each do |matcher, policy|
+        matched = matcher.is_a?(Regexp) ? matcher.match?(path) : matcher == path
+        return policy if matched
+      end
+
+      @policy
+    end
+
     # Standard headers go on every response. In html_only mode they are
     # restricted to 2xx HTML, as in 0.1.x.
-    def apply_standard_headers?(status, html)
-      return true unless @html_only
+    def apply_standard_headers?(policy, status, html)
+      return true unless policy.html_only
 
       success?(status) && html
     end
 
     # CSP goes on every HTML response regardless of status. In html_only mode
     # it is restricted to 2xx HTML, as in 0.1.x.
-    def apply_csp?(status, html)
+    def apply_csp?(policy, status, html)
       return false unless html
-      return true unless @html_only
+      return true unless policy.html_only
 
       success?(status)
     end
@@ -97,10 +263,6 @@ module HeaderGuard
       (200..299).cover?(status)
     end
 
-    def normalize_key(key)
-      key.to_s.downcase
-    end
-
     def html?(headers)
       content_type = fetch_header(headers, "content-type")
       return false unless content_type

data/lib/header_guard/version.rb

@@ -2,5 +2,5 @@
 
 module HeaderGuard
   # The current version of the HeaderGuard gem.
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: header_guard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Gemini AI