api_keys 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3183ee0be98a005fd2fc318937f9f8aeb6d8a6c0528a0b75d7234e55cde80480
-  data.tar.gz: 67080c1cddf08ee647657c8845a9332c61279249d8c9765ea0ad6fda4e4961a3
+  metadata.gz: 51db6ca1f89acc5b0638e33db41b88694b8be6275c3528a72012b3e2609d8736
+  data.tar.gz: 40c384e1af9d2befca96c4c5a3395daff9059ee19334ee01f997c59396367bdd
 SHA512:
-  metadata.gz: ff1adbe9b462443d7f278013030780bfc99ec2ef5acb6a814966a3530950147069bf33cc79d3d35ae8f6af8f76bf43b3a9a42d9692e22f9757df3c172b186535
-  data.tar.gz: 6f3f9febcd26069d345739d6268c8bcd4acce174ccdd2c24f915c8cfabf5404c2aa708e3538219ad8be30c8392d633101a6f1e52d7b099e123bf01474511859e
+  metadata.gz: 8ba7f9f769475fbf703446fa91ba19500393391eb1f1fa9b45eb5772fb46e044f8af492058d306c64bcf657c0c3654846d1d188916e4edaf7ee9e9a68571deed
+  data.tar.gz: f6ede6c7e458b1cdbac9cd580e46536ba735891e283c4a4e2eececbc4c194b91e36ca5756a43cf8b3ef80c9d5066fa50d35cdc59efa246543bbc5e85b3ebd352

data/CHANGELOG.md

@@ -1,4 +1,21 @@
-## [Unreleased]
+## [0.4.1] - 2026-08-24
+
+### Fixed
+
+- Stop the dashboard's Content Security Policy from blocking the host application's own stylesheets, scripts, and self-hosted webfonts. The 0.4.0 policy declared `default-src 'none'` with `script-src`/`style-src` reduced to the per-request nonce, but Rails only stamps that nonce onto `stylesheet_link_tag`/`javascript_include_tag` when the host application sets `content_security_policy_nonce_auto` (off by default, and not something an engine can enable for its host). Any application rendering its normal layout on engine pages got an unstyled, inert dashboard with no server-side error. The default policy now trusts same-origin scripts, styles, and fonts, adds `font-src`, and allows `https:` images, while keeping the nonce, `default-src 'self'`, `base-uri 'none'`, `object-src 'none'`, `frame-ancestors 'none'`, `frame-src 'none'`, `form-action 'self'`, and `connect-src 'self'`.
+- Stop generated install and authentication-index migrations from carrying an unreachable `migration_version` instance method; the generator already renders the Active Record version into each migration superclass.
+
+### Added
+
+- `config.dashboard_content_security_policy` selects the policy the mounted dashboard declares: `:default` (new default, hardened but compatible with a normal host layout), `:strict` (the 0.4.0 nonce-only policy, unchanged), or `false`/`nil` to declare nothing and leave the host application's policy alone. The setting is resolved per request and validated on assignment.
+
+### Upgrade notes
+
+- Applications that relied on the 0.4.0 nonce-only dashboard policy should set `config.dashboard_content_security_policy = :strict` to keep it. That policy requires a layout that serves nothing un-nonced on engine pages; the gem's built-in layout satisfies it, and host layouts additionally need `config.content_security_policy_nonce_auto = true`.
+
+### Maintenance
+
+- Move SimpleCov startup/reporting into the test helper and replace deprecated filtering/tracking APIs so the enforced line and branch coverage gates remain compatible with future SimpleCov releases.
 
 ## [0.4.0] - 2026-08-09
 

data/README.md

@@ -184,6 +184,8 @@ Tweak colors and spacing by overriding CSS variables in your application's style
 }
 ```
 
+Engine pages ship an enforcing Content Security Policy. The default allows same-origin scripts, styles, and fonts, so your own stylesheet loads normally — see [Dashboard Content Security Policy](#dashboard-content-security-policy) to tighten or disable it.
+
 #### Building Custom Integrations
 
 If you need complete control over the UI (e.g., to match your design system with Tailwind, Bootstrap, etc.), you can build your own views and controllers while using the gem's model layer and helpers.
@@ -973,6 +975,51 @@ Increase the TTL to reduce repeated lookup work without making cached state auth
 config.cache_ttl = 2.minutes
 ```
 
+### Dashboard Content Security Policy
+
+The mounted dashboard renders credential material, so it declares its own enforcing `Content-Security-Policy` on engine pages even when your application has none. You choose how strict it is:
+
+```ruby
+config.dashboard_content_security_policy = :default # :default (default), :strict, or false/nil
+```
+
+| Value | Behavior |
+|-------|----------|
+| `:default` | Hardened, but compatible with a normal host layout. |
+| `:strict` | Nonce-only: nothing loads unless it carries the engine's per-request nonce. |
+| `false` / `nil` | The gem declares nothing; your application's policy applies unchanged. |
+
+**`:default`** emits (nonce regenerated per request):
+
+```
+base-uri 'none'; object-src 'none'; frame-ancestors 'none'; frame-src 'none';
+form-action 'self'; connect-src 'self'; default-src 'self';
+script-src 'self' 'nonce-…'; style-src 'self' 'nonce-…';
+font-src 'self' data:; img-src 'self' https: data:
+```
+
+Framing, plugins, `<base>` hijacking, and cross-origin form posts stay blocked, and the dashboard's own inline `<style>`/`<script>` blocks stay nonce-gated — but your layout's stylesheets, scripts, and self-hosted webfonts still load.
+
+**`:strict`** restores the nonce-only policy: `default-src 'none'` with no source expression for scripts or styles, so the per-request nonce is the only thing that can run.
+
+```ruby
+config.dashboard_content_security_policy = :strict
+```
+
+Only use `:strict` if the layout rendered on engine pages serves nothing un-nonced. Rails does **not** put the nonce on `stylesheet_link_tag` / `javascript_include_tag` unless the host application opts in:
+
+```ruby
+# config/application.rb — required for :strict with a normal host layout
+config.content_security_policy_nonce_generator = ->(request) { SecureRandom.base64(16) }
+config.content_security_policy_nonce_auto = true
+```
+
+Without that, `:strict` blocks your layout's own asset tags and the dashboard renders unstyled and inert. The gem's built-in layout is fully self-contained and works under `:strict` as-is.
+
+**`false` / `nil`** leaves your application's policy completely alone. If your policy is nonce-based, allow the dashboard's nonced inline `<style>` and `<script>` yourself.
+
+Any directive the gem does not set is inherited from your application's policy.
+
 
 ## Callbacks: analytics, logging, usage monitoring & auditing
 

data/app/controllers/api_keys/application_controller.rb

@@ -18,25 +18,11 @@ module ApiKeys
     # The dashboard renders credential material, so give it an enforcing,
     # self-contained CSP even when the host application has not configured one.
     # Preserve any host directives we do not explicitly tighten.
-    before_action :prepare_api_keys_content_security_policy_nonce
-    if respond_to?(:content_security_policy)
-      content_security_policy do |policy|
-        policy.default_src :none
-        policy.base_uri :none
-        policy.object_src :none
-        policy.frame_ancestors :none
-        policy.frame_src :none
-        policy.form_action :self
-        # Rails appends the per-request nonce to these directives. `none` leaves
-        # the nonce as the only effective source instead of trusting every
-        # same-origin script or stylesheet.
-        policy.script_src :none
-        policy.style_src :none
-        policy.img_src :self, :data
-        policy.connect_src :self
-      end
-      content_security_policy_report_only false
-    end
+    #
+    # The policy is selected by `ApiKeys.configuration.dashboard_content_security_policy`
+    # and resolved per request, so host applications can relax or disable it from
+    # an initializer. See `apply_api_keys_content_security_policy` below.
+    before_action :apply_api_keys_content_security_policy
 
     # Ensure the owner is authenticated for all actions within this engine
     # This uses the configured authentication method (defaults to authenticate_user!)
@@ -45,6 +31,54 @@ module ApiKeys
 
     private
 
+    # Declares the dashboard's Content Security Policy for this request.
+    #
+    # `:default` keeps every structural protection (no framing, no plugins, no
+    # `<base>` hijacking, same-origin form submission) while still trusting
+    # same-origin scripts, styles, and fonts. That matters because Rails only
+    # stamps the per-request nonce onto `stylesheet_link_tag` / `javascript_include_tag`
+    # when the host sets `config.content_security_policy_nonce_auto`, which is off
+    # by default and which this engine cannot turn on for the host. Without a
+    # source expression the host layout's own asset tags are blocked and the
+    # dashboard renders unstyled and inert.
+    #
+    # `:strict` restores the nonce-only policy for applications whose layout
+    # serves nothing un-nonced on engine pages. `false`/`nil` declares nothing.
+    def apply_api_keys_content_security_policy
+      mode = ApiKeys.configuration.dashboard_content_security_policy
+      return unless mode # false/nil: leave the host application's policy alone
+      return unless request.respond_to?(:content_security_policy=)
+
+      prepare_api_keys_content_security_policy_nonce
+
+      policy = request.content_security_policy&.clone || ActionDispatch::ContentSecurityPolicy.new
+      policy.base_uri :none
+      policy.object_src :none
+      policy.frame_ancestors :none
+      policy.frame_src :none
+      policy.form_action :self
+      policy.connect_src :self
+
+      if mode == :strict
+        # Rails appends the per-request nonce to script-src/style-src. `none`
+        # leaves the nonce as the only effective source instead of trusting
+        # every same-origin script or stylesheet.
+        policy.default_src :none
+        policy.script_src :none
+        policy.style_src :none
+        policy.img_src :self, :data
+      else
+        policy.default_src :self
+        policy.script_src :self
+        policy.style_src :self
+        policy.font_src :self, :data
+        policy.img_src :self, :https, :data
+      end
+
+      request.content_security_policy = policy
+      request.content_security_policy_report_only = false if request.respond_to?(:content_security_policy_report_only=)
+    end
+
     def prepare_api_keys_content_security_policy_nonce
       return unless request.respond_to?(:content_security_policy_nonce_generator=)
 

data/lib/api_keys/configuration.rb

@@ -56,6 +56,20 @@ module ApiKeys
     # Engine UI Configuration
     attr_accessor :return_url, :return_text
 
+    # Dashboard Content Security Policy
+    #
+    # @!attribute [rw] dashboard_content_security_policy
+    #   @return [Symbol, false, nil] Which Content-Security-Policy the mounted
+    #     dashboard declares for its own pages.
+    #     - `:default` (default) — hardened but host-compatible: same-origin
+    #       scripts, styles, and fonts are allowed alongside the engine's
+    #       per-request nonce, so a host layout's asset tags keep working.
+    #     - `:strict` — nonce-only: `default-src 'none'` with no source
+    #       expression for scripts or styles. Requires a host layout that
+    #       serves no un-nonced assets on engine pages.
+    #     - `false` / `nil` — declare nothing and leave the host policy alone.
+    attr_reader :dashboard_content_security_policy
+
     # Debugging
     attr_reader :debug_logging
 
@@ -108,6 +122,7 @@ module ApiKeys
 
     VALID_HASH_STRATEGIES = %i[sha256 bcrypt].freeze
     VALID_TOKEN_ALPHABETS = %i[base58 hex].freeze
+    VALID_DASHBOARD_CONTENT_SECURITY_POLICIES = [:default, :strict, false, nil].freeze
     TOKEN_LENGTH_RANGE = (16..64)
     MAX_CONFIGURED_SCOPES = 100
     CONFIG_NAME_PATTERN = /\A[a-zA-Z0-9_-]{1,64}\z/
@@ -294,6 +309,23 @@ module ApiKeys
       @token_alphabet = value
     end
 
+    # Selects the Content-Security-Policy the dashboard declares for its own pages.
+    # `true` is accepted as an alias for `:default`; Strings are normalized to Symbols.
+    def dashboard_content_security_policy=(value)
+      normalized = case value
+                   when true then :default
+                   when String then value.to_sym
+                   else value
+                   end
+
+      unless VALID_DASHBOARD_CONTENT_SECURITY_POLICIES.include?(normalized)
+        raise ArgumentError,
+              "dashboard_content_security_policy must be :default, :strict, false, or nil"
+      end
+
+      @dashboard_content_security_policy = normalized
+    end
+
     def hash_strategy=(value)
       unless VALID_HASH_STRATEGIES.include?(value)
         raise ArgumentError, "hash_strategy must be one of: #{VALID_HASH_STRATEGIES.join(', ')}"
@@ -541,6 +573,12 @@ module ApiKeys
       @return_url = "/" # Default fallback path
       @return_text = "‹ Home" # Default link text
 
+      # Dashboard Content Security Policy
+      # Hardened, but compatible with a normal host layout: same-origin scripts,
+      # styles, and fonts load, and the engine's inline blocks stay nonce-gated.
+      # Use :strict for the nonce-only policy, or false/nil to declare nothing.
+      @dashboard_content_security_policy = :default
+
       # Debugging
       @debug_logging = false # Disable debug logging by default (warn and error get logged regardless of this)
 

data/lib/api_keys/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiKeys
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/lib/generators/api_keys/templates/add_authentication_index_to_api_keys.rb.erb

@@ -21,12 +21,4 @@ class AddAuthenticationIndexToApiKeys < ActiveRecord::Migration<%= migration_ver
     options[:algorithm] = :concurrently if connection.adapter_name.downcase.include?("postgres")
     remove_index :api_keys, **options
   end
-
-  private
-
-  def migration_version
-    major = ActiveRecord::VERSION::MAJOR
-    minor = ActiveRecord::VERSION::MINOR
-    major >= 5 ? "[#{major}.#{minor}]" : ""
-  end
 end

data/lib/generators/api_keys/templates/create_api_keys_table.rb.erb

@@ -94,15 +94,4 @@ class CreateApiKeysTable < ActiveRecord::Migration<%= migration_version %>
     # Fallback during initial setup or if connection isn't available
     :text
   end
-
-  # Provides the appropriate migration version syntax for the current Rails version.
-  def migration_version
-    major = ActiveRecord::VERSION::MAJOR
-    minor = ActiveRecord::VERSION::MINOR
-    if major >= 5
-      "[#{major}.#{minor}]"
-    else
-      ""
-    end
-  end
 end

data/lib/generators/api_keys/templates/initializer.rb

@@ -58,6 +58,24 @@ ApiKeys.configure do |config|
   # Default: "‹ Home"
   # config.return_text = "‹ Back to Settings"
 
+  # Content Security Policy for the mounted dashboard pages.
+  #
+  #   :default (default) - Hardened, but compatible with a normal host layout.
+  #                        Blocks framing, plugins, <base> hijacking, and
+  #                        cross-origin form posts, while allowing same-origin
+  #                        scripts, styles, and fonts so your layout's asset
+  #                        tags keep working.
+  #   :strict            - Nonce-only: no script or stylesheet loads unless it
+  #                        carries the engine's per-request nonce. Only use this
+  #                        if your layout serves nothing un-nonced on these pages
+  #                        (Rails only nonces asset tags when you also set
+  #                        config.content_security_policy_nonce_auto = true).
+  #   false / nil        - Declare nothing; your application's own policy applies
+  #                        unchanged. You then have to allow the dashboard's
+  #                        nonced inline <style>/<script> yourself.
+  #
+  # config.dashboard_content_security_policy = :default
+
   # ============================================================================
   # TOKEN PREFIXES
   # ============================================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_keys
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - rameerez