header_guard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c75619d9c42867f9748a930f0b82569401db387229f99fff65338652df173fd5
+  data.tar.gz: cb0c87a39bfd0157ef054f8386aaa38a78c6f207de292d857509ed210cda3e6a
+SHA512:
+  metadata.gz: 1f1845082fd922cc7636d97023edad724ac94fe36e702c71dee42d354fda3f9e2dc012a3e77af9f6ecc65f31d171c424219a7cc0b5746ef094a9b038dc5a8dcb
+  data.tar.gz: 724b5061a5c62e729b25c13ddf51e9af95e5926f6d97689116534353f7ec1f6228d8e0894bd75a5613602c0277052ecd4a6f769a75d9acbab199a783949ba1ee

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in header_guard.gemspec
+gemspec
+
+# Dependencies for development and testing
+group :development, :test do
+  gem "rack"
+  gem "rspec", "~> 3.12"
+  gem "rack-test"
+end

data/Gemfile.lock

@@ -0,0 +1,38 @@
+PATH
+  remote: .
+  specs:
+    header_guard (0.1.0)
+      rack (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    rack (3.2.3)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.5)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  header_guard!
+  rack
+  rack-test
+  rspec (~> 3.12)
+
+BUNDLED WITH
+   2.4.22

data/README.md

@@ -0,0 +1,167 @@
+HeaderGuard
+===========
+
+A robust and simple-to-use Rack middleware for enforcing modern HTTP security headers, including a highly configurable Content Security Policy (CSP).
+
+HeaderGuard is designed to automatically inject essential security headers like HSTS, X-Content-Type-Options, X-Frame-Options, and a customizable Content Security Policy, making your application significantly more resilient against XSS, clickjacking, and other common attacks.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'header_guard'
+```
+And then execute:
+
+```bash
+$ bundle install
+
+```
+Usage
+-----
+
+### Basic Setup (Recommended)
+
+To enable all default, secure headers, simply include the middleware in your Rack application (e.g., in a Rails config/application.rb or a Rack config.ru).
+
+**For Rails (in `config/application.rb`:**
+
+```ruby
+config.middleware.use HeaderGuard::Middleware
+```
+**For generic Rack apps (in config.ru):**
+
+```ruby
+require 'header_guard'
+use HeaderGuard::Middleware
+run YourApp.new
+```
+#### Environment-Specific Configuration (Development & Testing)
+For local development and testing, you often need to disable the strictest headers, like HSTS (which forces HTTPS) or the CSP (which can block inline scripts for tools).
+#### A. Disabling Headers in Development
+The simplest approach is to conditionally skip the middleware based on the Rails/Rack environment.
+
+**For Rails (in `config/application.rb`):**
+```ruby
+unless Rails.env.development? || Rails.env.test?
+  config.middleware.use HeaderGuard::Middleware
+end
+
+```
+#### B. Relaxing Specific Headers for Development
+
+If you only want to relax one or two headers (like HSTS) but keep the others, you can conditionally override the configuration.
+
+**For Rails (in an initializer like `config/initializers/header_guard.rb`):**
+```ruby
+# Start with an empty configuration hash
+header_options = {}
+
+if Rails.env.development? || Rails.env.test?
+  # 1. Disable Strict-Transport-Security for local HTTP development
+  header_options["Strict-Transport-Security"] = ""
+  
+  # 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';"
+  header_options[:content_security_policy] = dev_csp
+end
+
+# Apply the middleware with the environment-specific configuration
+Rails.application.config.middleware.use HeaderGuard::Middleware, header_options
+
+```
+
+
+
+### Configuration Options for Customization
+
+When integrating `HeaderGuard` into your project, you can pass an options hash to the middleware to customize or override any of the default security settings.
+
+#### 1\. Overriding Standard Headers
+
+Any key/value pair passed to the middleware that matches a standard header will override the default value.
+
+| Header | Default Value | Purpose | 
+ | ----- | ----- | ----- | 
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains; preload` | Enforces HTTPS usage. | 
+| `X-Content-Type-Options` | `nosniff` | Prevents browser MIME-sniffing. | 
+| `X-Frame-Options` | `DENY` | Prevents clickjacking (set to SAMEORIGIN to allow framing on the same site). | 
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | Controls referrer information sent with requests. | 
+
+**Example: Overriding X-Frame-Options and Referrer-Policy:**
+```ruby
+# In a Rails initializer or config.ru
+config.middleware.use HeaderGuard::Middleware, 
+  "X-Frame-Options" => "SAMEORIGIN",
+  "Referrer-Policy" => "no-referrer"
+```
+#### 2\. Custom Content Security Policy (CSP)
+
+You can define a custom CSP string to replace the secure default provided by HeaderGuard.
+
+```ruby
+custom_csp = "default-src 'self'; script-src 'self' [https://trusted.cdn.com](https://trusted.cdn.com);"
+use HeaderGuard::Middleware, content_security_policy: custom_csp
+
+```
+#### 3\. Report-Only Mode
+
+To test a new CSP without enforcing it, set the report\_only option to true. This will use the Content-Security-Policy-Report-Only header instead of the standard Content-Security-Policy header.
+
+```ruby
+# The browser will report violations but will not block resources.
+config.middleware.use HeaderGuard::Middleware, report_only: true
+
+```
+
+How It Works
+------------
+
+HeaderGuard hooks into the Rack request lifecycle and performs the following actions on responses with a 2xx status code and a Content-Type of text/html:
+
+1.  **Header Merging:** It takes the default security headers and merges them with any custom headers supplied during initialization, ensuring user configuration takes precedence.
+    
+2.  **Injection:** It injects the final set of standard security headers.
+    
+3.  **CSP Injection:** It injects the configured Content Security Policy, using either the standard enforcement header or the Report-Only header.
+    
+
+Development
+-----------
+
+After checking out the repository, run bundle install to install dependencies. Then, run rspec to execute the tests.
+This gem uses RSpec and Rack::Test for its testing suite.
+#### Prerequisites
+To set up the development environment, you will need:
+Ruby (version 2.6.6 or higher, as defined in the .gemspec)
+
+Bundler
+#### Setup and Testing
+1. Clone the repository:
+
+```bash
+git clone https://github.com/danielefrisanco/headerguard
+cd header_guard
+```
+
+2. Install all development and testing dependencies:
+
+```bash
+bundle install
+```
+
+3. Run the test suite using RSpec:
+
+```bash
+bundle exec rspec
+```
+
+(This ensures all tests, including the critical configuration override tests, are passing.)
+
+Contributing
+------------
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/danielefrisanco/headerguard](https://github.com/danielefrisanco/headerguard).

data/header_guard.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/header_guard/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "header_guard"
+  spec.version       = HeaderGuard::VERSION
+  spec.authors       = ["Gemini AI", "Daniele Frisanco"]
+  spec.email         = ["daniele.frisanco@gmail.com"]
+
+  spec.summary       = "A robust Rack middleware for enforcing modern HTTP security headers, including a highly configurable Content Security Policy (CSP)."
+  spec.description   = "Designed for applications that require strong browser-side security, HeaderGuard automatically injects HSTS, X-Content-Type-Options, X-Frame-Options, and a customizable CSP. Ideal for SSO and high-security web services."
+  spec.homepage      = "https://github.com/placeholder/header_guard"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.6.6" 
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == spec.full_name + ".gem") ||
+        f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_runtime_dependency "rack", "~> 3.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "rack-test"
+end

data/lib/header_guard/middleware.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module HeaderGuard
+  # The Rack middleware class responsible for injecting security headers.
+  class Middleware
+    # 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.
+    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
+
+      # 1. Start with DEFAULT_HEADERS (from header_guard.rb)
+      # 2. Merge remaining options (which are custom headers) over the defaults.
+      # THIS IS THE FIX: By merging 'config' (which now only contains headers)
+      # over the defaults, the user's header values take precedence.
+      @headers = DEFAULT_HEADERS.merge(config).freeze
+
+      # 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"
+    end
+
+    # The Rack application call method.
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      # Only inject headers on successful (2xx) responses with HTML content.
+      # Exclude redirects, errors, and non-HTML assets (like JSON or images).
+      if (200..299).include?(status) && headers["Content-Type"]&.include?("text/html")
+        
+        # Inject the standard headers
+        @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.
+          headers[key] = value 
+        end
+        
+        # Inject the configured CSP header
+        headers[@csp_header_key] = @csp_value
+      end
+
+      [status, headers, body]
+    end
+  end
+end

data/lib/header_guard/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module HeaderGuard
+  # The current version of the HeaderGuard gem.
+  VERSION = "0.1.0"
+end

data/lib/header_guard.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "header_guard/version"
+require_relative "header_guard/middleware"
+
+module HeaderGuard
+  # Standard security headers applied by default.
+  DEFAULT_HEADERS = {
+    # Strictly enforce HTTPS, preventing protocol downgrade attacks.
+    # 1 year (31536000 seconds) max-age is standard best practice.
+    "Strict-Transport-Security"   => "max-age=31536000; includeSubDomains; preload",
+    # Prevent the browser from trying to guess the content type,
+    # which can lead to XSS attacks if it misinterprets a file as a script.
+    "X-Content-Type-Options"      => "nosniff",
+    # Tells the browser which referrer information to include with requests.
+    # origin-when-cross-origin is a good balance of security and functionality.
+    "X-Frame-Options"             => "DENY",
+    # Tells the browser which referrer information to include with requests.
+    # origin-when-cross-origin is a good balance of security and functionality.
+    "Referrer-Policy"             => "strict-origin-when-cross-origin"
+  }.freeze
+
+  # Default Content Security Policy. This is a secure baseline.
+  # This serves as a strong baseline, allowing resources only from the same origin ('self'),
+  # and explicitly blocking all plugins, base tags, and object embeds.
+  #
+  # Note: A real application will likely need to customize this heavily
+  # to allow CDNs, analytics scripts, etc.
+  DEFAULT_CSP = (
+    "default-src 'self';" \
+    "base-uri 'self';" \
+    "font-src 'self' https: data:;" \
+    "form-action 'self';" \
+    "frame-ancestors 'none';" \
+    "object-src 'none';" \
+    "script-src 'self';" \
+    "style-src 'self' 'unsafe-inline' https:;" \
+    "upgrade-insecure-requests;" \
+    "block-all-mixed-content"
+  ).freeze
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: header_guard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gemini AI
+- Daniele Frisanco
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Designed for applications that require strong browser-side security,
+  HeaderGuard automatically injects HSTS, X-Content-Type-Options, X-Frame-Options,
+  and a customizable CSP. Ideal for SSO and high-security web services.
+email:
+- daniele.frisanco@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- header_guard.gemspec
+- lib/header_guard.rb
+- lib/header_guard/middleware.rb
+- lib/header_guard/version.rb
+homepage: https://github.com/placeholder/header_guard
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key: 
+specification_version: 4
+summary: A robust Rack middleware for enforcing modern HTTP security headers, including
+  a highly configurable Content Security Policy (CSP).
+test_files: []