csp_maker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a645c19c334a4c1b70f46a7b7afec40bd91dd05205de493cd690ca97d254affb
+  data.tar.gz: 12ab705a8aa1ca92f4843e3355e068959bb39a234f90cb7e1a4bfc52b6d4c313
+SHA512:
+  metadata.gz: 9a41bb604a093794b6ea224093e56e4bfd1272f31e1203ce0feb9673f3545cc39d093901412aeb7f5d036d881a1bbe11b2a43e8c1444fd97a0a91eef7f9439f9
+  data.tar.gz: 6a13a9fb9cee3bd78cee4fe158053c1fe75fd0439da1d437e183c31e3aeb19b6c17ec30fa7c2b69353af68f60dca4bd9e27109db852ffdd82b11accc191b0f29

data/CHANGELOG.md

@@ -0,0 +1 @@
+## [Unreleased]

data/README.md

@@ -0,0 +1,200 @@
+# CSP Maker
+
+CSP Maker is a micro gem in Ruby for defining a [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy), extracted from Rails so it can be used standalone or in Rack apps.
+
+The code is extracted from [ActionDispatch::ContentSecurityPolicy](https://github.com/rails/rails/blob/main/actionpack/lib/action_dispatch/http/content_security_policy.rb) in Action Pack, with some minor modifications. The DSL as described in Rails docs should be usable 1:1 here. There is also an optional Rack middleware updated to not rely on Rails internals.
+
+
+## Installation
+
+Add the gem to your app's `Gemfile`:
+
+    gem 'csp_maker', '~> 0.1'
+
+Then, require it in your server code:
+
+```rb
+require 'csp_maker'
+```
+
+CSP Maker supports Ruby 3.0 and newer.
+
+
+## Basic usage
+
+The simplest way is through the `CSPMaker.build_policy` method:
+
+```rb
+headers['Content-Security-Policy'] = CSPMaker.build_policy do |p|
+  p.default_src :none
+  p.script_src :self, 'https://github.com', 'https://example.com'
+  p.style_src :self
+  p.font_src :self
+  p.img_src :self, :https, :data
+  p.connect_src :self, 'https://api.bsky.app'
+  p.base_uri :none
+  p.object_src :none
+end
+```
+
+This creates a `ContentSecurityPolicy` definition object and then immediately encodes it into the final string, which you can assign to the target header.
+
+Alternatively, you can also pass a block without parameters and call the DSL methods on an implicit `self` like this:
+
+```rb
+headers['Content-Security-Policy'] = CSPMaker.build_policy do
+  default_src :none
+  script_src :self, 'https://github.com', 'https://example.com'
+  style_src :self
+  font_src :self
+  img_src :self, :https, :data
+  connect_src :self, 'https://api.bsky.app'
+  base_uri :none
+  object_src :none
+end
+```
+
+Note, in this case (block without parameters) the block is run through `instance_eval` in the context of the policy object, so helper methods and instance vars from outside the block won't be accessible inside; if you want to use those, use the version with a parameter, or call the `ContentSecurityPolicy` constructor directly.
+
+If you want to use nonces, you can generate a nonce yourself and pass it to the DSL using a new `nonce()` DSL method like this:
+
+```rb
+asset_nonce = ...
+
+headers['Content-Security-Policy'] = CSPMaker.build_policy do
+  default_src :none
+  script_src :self, nonce(asset_nonce)
+end
+```
+
+A second approach is to use `CSPMaker.define_policy` to create a policy definition once, and then reuse it on each request:
+
+```rb
+CSP = CSPMaker.define_policy do
+  default_src :none
+  script_src :self, 'https://github.com', 'https://example.com'
+  style_src :self
+  ...
+end
+```
+
+You encode the policy into the header string by calling `#build(context, nonce, nonce_directives)`. The parameters (all optional) are:
+
+- `context` – you can pass a Proc instead of a String/Symbol to a DSL directive, and that Proc will be called with this context object as `self` (it can be e.g. some kind of controller or request object)
+- `nonce` – a nonce to be added to the designated directives
+- `nonce_directives` – array of directives to which nonces should be added; if nil, the list is read from a global setting `CSPMaker.nonce_directives`, or the default `['script-src', 'style-src']`
+
+So it can look like this:
+
+```rb
+asset_nonce = ...
+
+headers['Content-Security-Policy'] = CSP.build(nil, asset_nonce, ['script-src'])
+```
+
+
+## Rack middleware
+
+A third way is to use the Rack middleware. The middleware class is also taken from the Rails code, but simplified to not rely on Rails internals.
+
+Require the `csp_maker/rack` file instead of `csp_maker`:
+
+```rb
+require 'csp_maker/rack'
+```
+
+Define a policy, and pass it to the `CSPMaker::Middleware` when installing it into the Rack stack:
+
+```rb
+policy = CSPMaker.define_policy {
+  ...
+}
+
+use CSPMaker::Middleware, policy
+```
+
+The middleware will:
+
+- automatically generate a nonce, append it to the directives and store it in the Rack `env`, if a nonce generator is configured (see below)
+- store the generated nonce in the `env` under `csp_maker.nonce` (`CSPMaker::Middleware::NONCE_ENV_KEY`)
+- create a `Rack::Request` object and use it as the block context for any Procs in the DSL
+- encode the policy into a result string
+- assign it to the `content-security-policy` header automatically
+
+
+## Using nonces
+
+When using the Rack middleware, if you want it to append nonces, you need to assign a nonce generator Proc to `CSPMaker.nonce_generator` (equivalent of `config.content_security_policy_nonce_generator` in Rails), or pass it as a `nonce_generator:` option to the `Middleware` initializer. You can use `CSPMaker.default_generator`, which calls `SecureRandom.base64(16)`:
+
+```rb
+CSPMaker.nonce_generator = CSPMaker.default_generator
+
+# or:
+
+CSPMaker.nonce_generator = -> { ... }
+```
+
+Use `CSPMaker.nonce_directives` (equivalent of `config.content_security_policy_nonce_directives` in Rails) or `nonce_directives:` option in `Middleware` to configure which directives should have a nonce added to them (default is `['script-src', 'style-src']`):
+
+```rb
+CSPMaker.nonce_directives = ['script-src']
+
+# or:
+
+use CSPMaker::Middleware, policy, nonce_generator: -> { ... }, nonce_directives: ['style-src']
+```
+
+The generated nonce is stored in the `env` hash under `csp_maker.nonce` (`CSPMaker::Middleware::NONCE_ENV_KEY`). You will need it for the view template code to add it to the inline `script` / `style` tags, so you could add a helper like:
+
+```rb
+def asset_nonce
+  request.env[CSPMaker::Middleware::NONCE_ENV_KEY]
+end
+```
+
+When using `build_policy` or `define_policy` standalone without a middleware, generating and storing the nonce is up to you – and you either pass it to `nonce(...)` inside a `build_policy` block, or as the second argument to `#build` on a `CSPMaker::ContentSecurityPolicy` object returned from `define_policy`. However, you can also assign `CSPMaker.nonce_generator` and call `CSPMaker.make_nonce` to run it if you want:
+
+```rb
+CSPMaker.nonce_generator = CSPMaker.default_generator
+
+policy = CSPMaker.define_policy { ... }
+nonce = CSPMaker.make_nonce
+
+headers['content-security-policy'] = policy.build(nil, nonce)
+```
+
+
+## Other options
+
+You can also set `CSPMaker.report_only` (equivalent of `config.content_security_policy_report_only` in Rails) or `report_only:` option to `Middleware` to assign the policy to the `content-security-policy-report-only` header instead of `content-security-policy`; this makes the browser only report errors to the URL configured via `report_uri` in the DSL, but not actually enforce the policy in the web app (i.e. not block any scripts & styles from loading).
+
+
+## Full DSL API
+
+Directives:
+
+* directives that accept an array of sources: `base_uri`, `child_src`, `connect_src`, `default_src`, `font_src`, `form_action`, `frame_ancestors`, `frame_src`, `img_src`, `manifest_src`, `media_src`, `object_src`, `prefetch_src`, `require_trusted_types_for`, `script_src`, `script_src_attr`, `script_src_elem`, `style_src`, `style_src_attr`, `style_src_elem`, `trusted_types`, `worker_src`
+* `block_all_mixed_content(enabled = true)`
+* `plugin_types(*types)`
+* `report_uri(uri)`
+* `require_sri_for(*types)`
+* `sandbox(enabled = true)` or `sandbox(*values)`
+* `upgrade_insecure_requests(enabled = true)`
+
+Source lists:
+
+* special values: `:allow_duplicates`, `:none`, `:report_sample`, `:script`, `:self`, `:strict_dynamic`, `:unsafe_eval`, `:unsafe_hashes`, `:unsafe_inline`, `:wasm_unsafe_eval`
+* protocols: `:http`, `:https`, `:data`, `:mediastream`, `:blob`, `:filesystem`, `:ws`, `:wss`
+* content hashes: `"sha256-..."`, `"sha384-..."`, `"sha512-..."`
+* `nonce(nonce_value)`
+
+
+## Credits
+
+The original `content_security_policy.rb` was added to Rails ActionPack code by Andrew White in 2017, and had some updates since then by others.
+
+Modifications for the purposes of this gem are © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
+
+The code is available under the terms of the [MIT license](https://choosealicense.com/licenses/mit/).
+
+Bug reports and pull requests are welcome :)

data/lib/csp_maker/csp.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+# Configures the HTTP [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
+# response header to help protect against XSS and injection attacks.
+#
+# Example global policy:
+#
+#     CSPMaker.build_policy do |policy|
+#       policy.default_src :self, :https
+#       policy.font_src    :self, :https, :data
+#       policy.img_src     :self, :https, :data
+#       policy.object_src  :none
+#       policy.script_src  :self, :https
+#       policy.style_src   :self, :https
+#
+#       # Specify URI for violation reports
+#       policy.report_uri "/csp-violation-report-endpoint"
+#     end
+
+module CSPMaker
+  class InvalidDirectiveError < StandardError
+  end
+
+  class ContentSecurityPolicy
+    MAPPINGS = {
+      self:             "'self'",
+      unsafe_eval:      "'unsafe-eval'",
+      wasm_unsafe_eval: "'wasm-unsafe-eval'",
+      unsafe_hashes:    "'unsafe-hashes'",
+      unsafe_inline:    "'unsafe-inline'",
+      none:             "'none'",
+      http:             "http:",
+      https:            "https:",
+      data:             "data:",
+      mediastream:      "mediastream:",
+      allow_duplicates: "'allow-duplicates'",
+      blob:             "blob:",
+      filesystem:       "filesystem:",
+      report_sample:    "'report-sample'",
+      script:           "'script'",
+      strict_dynamic:   "'strict-dynamic'",
+      ws:               "ws:",
+      wss:              "wss:"
+    }.freeze
+
+    DIRECTIVES = {
+      base_uri:                   "base-uri",
+      child_src:                  "child-src",
+      connect_src:                "connect-src",
+      default_src:                "default-src",
+      font_src:                   "font-src",
+      form_action:                "form-action",
+      frame_ancestors:            "frame-ancestors",
+      frame_src:                  "frame-src",
+      img_src:                    "img-src",
+      manifest_src:               "manifest-src",
+      media_src:                  "media-src",
+      object_src:                 "object-src",
+      prefetch_src:               "prefetch-src",
+      require_trusted_types_for:  "require-trusted-types-for",
+      script_src:                 "script-src",
+      script_src_attr:            "script-src-attr",
+      script_src_elem:            "script-src-elem",
+      style_src:                  "style-src",
+      style_src_attr:             "style-src-attr",
+      style_src_elem:             "style-src-elem",
+      trusted_types:              "trusted-types",
+      worker_src:                 "worker-src"
+    }.freeze
+
+    HASH_SOURCE_ALGORITHM_PREFIXES = ["sha256-", "sha384-", "sha512-"].freeze
+
+    DEFAULT_NONCE_DIRECTIVES = %w[script-src style-src].freeze
+
+    private_constant :MAPPINGS, :DIRECTIVES, :DEFAULT_NONCE_DIRECTIVES
+
+    attr_reader :directives
+
+    def initialize
+      @directives = {}
+      yield self if block_given?
+    end
+
+    def initialize_copy(other)
+      @directives = other.directives.to_h do |directive, sources|
+        if sources.is_a?(Array)
+          copied_sources = sources.map { |source| source.is_a?(String) ? source.dup : source }
+          [directive, copied_sources]
+        else
+          [directive, sources]
+        end
+      end
+    end
+
+    DIRECTIVES.each do |name, directive|
+      define_method(name) do |*sources|
+        if sources.first
+          @directives[directive] = apply_mappings(sources)
+        else
+          @directives.delete(directive)
+        end
+      end
+    end
+
+    # Specify whether to prevent the user agent from loading any assets over HTTP
+    # when the page uses HTTPS:
+    #
+    #     policy.block_all_mixed_content
+    #
+    # Pass `false` to allow it again:
+    #
+    #     policy.block_all_mixed_content false
+    #
+
+    def block_all_mixed_content(enabled = true)
+      if enabled
+        @directives["block-all-mixed-content"] = true
+      else
+        @directives.delete("block-all-mixed-content")
+      end
+    end
+
+    # Restricts the set of plugins that can be embedded:
+    #
+    #     policy.plugin_types "application/x-shockwave-flash"
+    #
+    # Leave empty to allow all plugins:
+    #
+    #     policy.plugin_types
+
+    def plugin_types(*types)
+      if types.first
+        @directives["plugin-types"] = types
+      else
+        @directives.delete("plugin-types")
+      end
+    end
+
+    # Enable the [report-uri](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-uri)
+    # directive. Violation reports will be sent to the specified URI:
+    #
+    #     policy.report_uri "/csp-violation-report-endpoint"
+
+    def report_uri(uri)
+      @directives["report-uri"] = [uri]
+    end
+
+    # Specify asset types for which [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
+    # is required:
+    #
+    #     policy.require_sri_for :script, :style
+    #
+    # Leave empty to not require Subresource Integrity:
+    #
+    #     policy.require_sri_for
+
+    def require_sri_for(*types)
+      if types.first
+        @directives["require-sri-for"] = types
+      else
+        @directives.delete("require-sri-for")
+      end
+    end
+
+    # Specify whether a [sandbox](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox)
+    # should be enabled for the requested resource:
+    #
+    #     policy.sandbox
+    #
+    # Values can be passed as arguments:
+    #
+    #     policy.sandbox "allow-scripts", "allow-modals"
+    #
+    # Pass `false` to disable the sandbox:
+    #
+    #     policy.sandbox false
+
+    def sandbox(*values)
+      if values.empty?
+        @directives["sandbox"] = true
+      elsif values.first
+        @directives["sandbox"] = values
+      else
+        @directives.delete("sandbox")
+      end
+    end
+
+    # Specify whether user agents should treat any assets over HTTP as HTTPS:
+    #
+    #     policy.upgrade_insecure_requests
+    #
+    # Pass `false` to disable it:
+    #
+    #     policy.upgrade_insecure_requests false
+
+    def upgrade_insecure_requests(enabled = true)
+      if enabled
+        @directives["upgrade-insecure-requests"] = true
+      else
+        @directives.delete("upgrade-insecure-requests")
+      end
+    end
+
+    def nonce(nonce)
+      raise InvalidDirectiveError, "Nonce must be a non-empty string" unless nonce.is_a?(String) && nonce.length > 0
+
+      "'nonce-#{nonce}'"
+    end
+
+    def build(context = nil, nonce = nil, nonce_directives = nil)
+      nonce_directives ||= CSPMaker.nonce_directives || DEFAULT_NONCE_DIRECTIVES
+      build_directives(context, nonce, nonce_directives).compact.join("; ")
+    end
+
+
+    private
+
+    def apply_mappings(sources)
+      sources.map do |source|
+        case source
+        when Symbol
+          apply_mapping(source)
+        when String
+          if hash_source?(source)
+            "'#{source}'"
+          else
+            source
+          end
+        when Proc
+          source
+        else
+          raise ArgumentError, "Invalid content security policy source: #{source.inspect}"
+        end
+      end
+    end
+
+    def apply_mapping(source)
+      MAPPINGS.fetch(source) do
+        raise ArgumentError, "Unknown content security policy source mapping: #{source.inspect}"
+      end
+    end
+
+    def build_directives(context, nonce, nonce_directives)
+      @directives.map do |directive, sources|
+        if sources.is_a?(Array)
+          if nonce && nonce_directive?(directive, nonce_directives)
+            "#{directive} #{build_directive(directive, sources, context).join(' ')} 'nonce-#{nonce}'"
+          else
+            "#{directive} #{build_directive(directive, sources, context).join(' ')}"
+          end
+        elsif sources
+          directive
+        else
+          nil
+        end
+      end
+    end
+
+    def validate(directive, sources)
+      sources.each do |source|
+        if source.include?(";") || source =~ /[[:space:]]/
+          message =
+            "Invalid Content Security Policy #{directive}: #{source.inspect}. " +
+            "Directive values must not contain whitespace or semicolons. " +
+            "Please use multiple arguments or other directive methods instead."
+
+          raise InvalidDirectiveError, message
+        end
+      end
+    end
+
+    def build_directive(directive, sources, context)
+      resolved_sources = sources.flat_map { |source| resolve_source(source, context) }
+
+      validate(directive, resolved_sources)
+
+      resolved_sources
+    end
+
+    def resolve_source(source, context)
+      case source
+      when String
+        source
+      when Symbol
+        source.to_s
+      when Proc
+        if context.nil?
+          raise RuntimeError, "Missing context for the dynamic content security policy source: #{source.inspect}"
+        else
+          resolved = context.instance_exec(&source)
+          apply_mappings(wrap_array(resolved))
+        end
+      else
+        raise RuntimeError, "Unexpected content security policy source: #{source.inspect}"
+      end
+    end
+
+    def wrap_array(object)
+      if object.nil?
+        []
+      elsif object.respond_to?(:to_ary)
+        object.to_ary || [object]
+      else
+        [object]
+      end
+    end
+
+    def nonce_directive?(directive, nonce_directives)
+      nonce_directives.include?(directive)
+    end
+
+    def hash_source?(source)
+      source.start_with?(*HASH_SOURCE_ALGORITHM_PREFIXES)
+    end
+  end
+end

data/lib/csp_maker/rack.rb

@@ -0,0 +1,55 @@
+require_relative '../csp_maker'
+require 'rack'
+
+module CSPMaker
+  class Middleware
+    CONTENT_SECURITY_POLICY = "content-security-policy"
+    CONTENT_SECURITY_POLICY_REPORT_ONLY = "content-security-policy-report-only"
+    NONCE_ENV_KEY = "csp_maker.nonce"
+
+    def initialize(app, policy,
+      report_only: CSPMaker.report_only,
+      nonce_generator: CSPMaker.nonce_generator,
+      nonce_directives: CSPMaker.nonce_directives)
+
+      @app = app
+      @policy = policy
+      @report_only = report_only
+      @nonce_generator = nonce_generator
+      @nonce_directives = nonce_directives
+    end
+
+    def call(env)
+      nonce = make_nonce(env) if @nonce_generator
+  
+      status, headers, _ = response = @app.call(env)
+
+      # Returning CSP headers with a 304 Not Modified is harmful, since nonces in the
+      # new CSP headers might not match nonces in the cached HTML.
+      return response if status == 304
+
+      return response if policy_present?(headers)
+
+      request = Rack::Request.new(env)
+      headers[header_name] = @policy.build(request, nonce, @nonce_directives)
+
+      response
+    end
+
+    private
+
+    def make_nonce(env)
+      if @nonce_generator
+        env[NONCE_ENV_KEY] ||= @nonce_generator.call
+      end
+    end
+
+    def header_name
+      @report_only ? CONTENT_SECURITY_POLICY_REPORT_ONLY : CONTENT_SECURITY_POLICY
+    end
+
+    def policy_present?(headers)
+      headers[CONTENT_SECURITY_POLICY] || headers[CONTENT_SECURITY_POLICY_REPORT_ONLY]
+    end
+  end
+end

data/lib/csp_maker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CSPMaker
+  VERSION = '0.1.0'
+end

data/lib/csp_maker.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'csp_maker/csp'
+require_relative 'csp_maker/version'
+
+require 'securerandom'
+
+module CSPMaker
+  class << self
+    attr_accessor :report_only, :nonce_generator, :nonce_directives
+
+    def build_policy(context = nil, &block)
+      raise ArgumentError, "block required" unless block_given?
+
+      policy = define_policy(&block)
+      policy.build(context)
+    end
+
+    def define_policy(&block)
+      raise ArgumentError, "block required" unless block_given?
+
+      policy = ContentSecurityPolicy.new
+
+      if block.parameters.empty?
+        policy.instance_eval(&block)
+      else
+        block.call(policy)
+      end
+
+      policy
+    end
+
+    def default_generator
+      proc { SecureRandom.base64(16) }
+    end
+
+    def make_nonce
+      nonce_generator.call
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: csp_maker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kuba Suder
+bindir: bin
+cert_chain: []
+date: 1980-01-02 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'
+description: "\n    CSP Maker lets you define a Content Security Policy using a DSL
+  and encode it into a header string.\n    It has support for nonces, and includes
+  a Rack middleware that automates generating and assigning\n    the header.\n\n    The
+  code was extracted from ActionDispatch::ContentSecurityPolicy in Rails ActionPack,
+  with some\n    minor modifications. The DSL as described in Rails docs should be
+  usable 1:1 here.\n  "
+email:
+- jakub.suder@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/csp_maker.rb
+- lib/csp_maker/csp.rb
+- lib/csp_maker/rack.rb
+- lib/csp_maker/version.rb
+homepage: https://tangled.org/mackuba.eu/csp_maker
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://tangled.org/mackuba.eu/csp_maker/issues
+  changelog_uri: https://tangled.org/mackuba.eu/csp_maker/blob/master/CHANGELOG.md
+  source_code_uri: https://tangled.org/mackuba.eu/csp_maker
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A micro gem for defining a Content Security Policy using a DSL, extracted
+  from Rails
+test_files: []