maquina-generators 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8023146b756cacff577544a89e379d751c5f4f1e1df5fd1cb61932a514049bd
-  data.tar.gz: 1bff652af72d0e15d9dbd66e90e758b8f900200d5ae5dbd5c783157cfaa49f3a
+  metadata.gz: 8127a7f3efbfaea2bb59f4c0b0977476fd7bc4d176d634d294d9520dd3a10f83
+  data.tar.gz: ef59f91d08b1f3bb99343f28564e5d4c07972201724e3c58a7ee37b1ab93c07f
 SHA512:
-  metadata.gz: 882a19b2e1d69f38e9acc0e73a312bb5a9750155b7521c6a2dc9597ddb93c1934c83536d5525a74916b7750a49f3bfd94543bd09dcd01a43a2aa2d8b0525d794
-  data.tar.gz: b9a6a548f3b6dbf7f6871e68588066f97bad710e2fc5a978dc9dcb32636b2448c60c86928dbc874b87cc4b3012030f94becc893049635418fb0df6e29e19b474
+  metadata.gz: 61d953a6567afb896d605dcf653bd8cd71d192fa81d043262157b32f915847f70e22bc74575cc35468f093b00532a0d910e39108fc6d0224ae7a6b5813fe832b
+  data.tar.gz: 7e65996ad9c0e7e61bbd8ce5774432df06a8176005741b68ba2c3757cbaffa42439e1bacae486b5966e4b3801470d8d506e5a6c019c2bb4d95e9615cb2beb7a2

data/README.md

@@ -19,6 +19,8 @@ A collection of Rails generators from the Maquina umbrella. Each generator produ
 - **Migrations:** 4 migrations (accounts, users, sessions, email_verifications)
 - **Test helper:** `sign_in_as(user)` and `sign_out` for integration tests
 
+Sign-in codes are encrypted at rest with Active Record encryption and compared in constant time. The generator adds the encryption keys to `config/credentials.yml.enc` when they are missing; without a master key, run `bin/rails db:encryption:init`.
+
 #### Installation
 
 Add to your Gemfile:
@@ -55,10 +57,64 @@ All generated code lives in your app -- edit it directly:
 - **Session duration:** Edit `authentication.rb` (default: 30 days)
 - **Code expiration:** Edit controllers (default: 15 minutes)
 - **Cooldown between codes:** Edit `EmailVerification::COOLDOWN_MINUTES` (default: 15)
+- **Wrong guesses before a code locks:** Edit `EmailVerification::MAX_ATTEMPTS` (default: 5)
 - **Colors/styling:** Edit view templates (default: indigo)
 - **Email sender:** Edit `app/mailers/verification_mailer.rb`
 - **Translations:** Edit `config/locales/clave.*.yml`
 
+### Passkeys -- Passkey Sign-In for Clave
+
+**Passkeys** adds WebAuthn passkeys as a second way to sign in, on top of Clave. People add passkeys from a `/passkeys` page and sign in with Face ID, a fingerprint or a device PIN, either with a button or straight from the email field's autofill. The email code stays as the way in without a passkey, so removing every passkey never locks anyone out.
+
+The [`webauthn`](https://github.com/cedarcode/webauthn-ruby) gem handles only the cryptography (attestation and assertion parsing, signature, origin, challenge and user-verification checks). The flow itself, including controllers, model, views and JavaScript, is generated into your app. There is no JavaScript dependency: the Stimulus controllers use the browser's own `PublicKeyCredential.parseCreationOptionsFromJSON` / `parseRequestOptionsFromJSON` / `toJSON()`. The names (`passkeys` table, `credential_id`, `Session::PasskeysController`) follow the passkeys work proposed for Rails itself (rails/rails#57100).
+
+#### What it generates
+
+- **Gem:** `webauthn ~> 3.4`
+- **Initializer:** `config/initializers/webauthn.rb`. The relying party is `localhost` in development; production reads `WEBAUTHN_RP_ID` / `WEBAUTHN_ORIGINS` (or `webauthn:` in credentials) and refuses to boot without them, except during the asset build.
+- **Models:** `Passkey` (credential id, public key, sign count, transports, AAGUID, backup flags, last used) and `User#webauthn_id`, a random user handle created on first use
+- **Sign-in:** `Session::PasskeyChallengesController` and `Session::PasskeysController`. These need no email (discoverable credentials, empty allow-list), require user verification, use each challenge once and expire it after 5 minutes, and sign in through Clave's `start_new_session_for`. An unknown credential gets a 404 so the browser can forget it (`signalUnknownCredential`).
+- **Management:** `PasskeysController` and `PasskeyChallengesController` to add, rename and remove passkeys. Adding or removing a passkey needs a sign-in from the last 30 minutes (`PasskeyReauthentication::REAUTHENTICATE_AFTER`).
+- **Views and JavaScript:** `passkeys/index`, a `sessions/_passkey` partial rendered on the sign-in page (and `autocomplete="username webauthn"` on its email field), plus `passkey_sign_in_controller.js` and `passkey_registration_controller.js`
+- **Migrations:** `add_webauthn_id_to_users`, `create_passkeys`
+- **Locale files:** English and Spanish
+- **Rack::Attack:** a `passkey/ip` throttle when `config/initializers/rack_attack.rb` exists
+- **Tests:** a `register_passkey` and `sign_in_with_passkey(user)` helper on top of `WebAuthn::FakeClient`, loaded from `test/test_helper.rb`, and `test/integration/passkeys_test.rb` covering the flow. The test creates users the way Clave's `User` does, so adjust its `setup` if your model differs.
+
+#### Usage
+
+```bash
+rails g maquina:clave      # first
+rails g maquina:passkeys
+rails db:migrate
+```
+
+Then link to `passkeys_path` from your account or settings page. Anything the generator cannot place safely (a `User` model or sign-in page that no longer has Clave's shape) is listed after the install instead of being forced.
+
+#### Options
+
+```bash
+rails g maquina:passkeys               # Full install
+rails g maquina:passkeys --skip-views  # Endpoints only; bring your own UI
+```
+
+#### Production
+
+Passkeys are bound to a domain, and changing `rp_id` later orphans every saved passkey. Set it before the first user adds one:
+
+```bash
+WEBAUTHN_RP_ID=example.com
+WEBAUTHN_ORIGINS=https://example.com,https://app.example.com
+```
+
+`rp_id` can be a parent of the origins' host. To serve passkeys across different domains, publish `/.well-known/webauthn` (Related Origin Requests).
+
+#### Testing
+
+- **Integration tests:** `register_passkey` and `sign_in_with_passkey(user)` go through the real endpoints with `WebAuthn::FakeClient`.
+- **In a browser:** Chrome's virtual authenticator works in DevTools (More tools > WebAuthn) or over CDP (`WebAuthn.addVirtualAuthenticator` with `ctap2`, `internal`, a resident key and user verification). It answers the sign-in page's autofill request on its own, so loading `/session/new` signs you in without a click. To test the button, make `PublicKeyCredential.isConditionalMediationAvailable` return `false`.
+- **Dev server on another port:** set `WEBAUTHN_ORIGINS=http://localhost:<port>`.
+
 ### Registration -- Password-Based Authentication with Accounts
 
 **Registration** generates a password-based authentication system with multi-tenant account support. It builds on top of the Rails 8 authentication generator, adding an Account model (tenant), user roles, and a registration flow.
@@ -322,6 +378,34 @@ Development's `:memory_store` keeps bans inside the server process, so they rese
 
 ---
 
+### CSP Reports -- Content Security Policy Violation Endpoint
+
+**CSP Reports** gives the browser somewhere to send Content Security Policy violations and shows them on the Security page. It needs `maquina:security`, whose `security` database stores them.
+
+#### What it generates
+
+- **Controller:** `CspReportsController` at `POST /csp-reports` -- an API controller with no session or CSRF that accepts both the legacy `report-uri` body and the Reporting API body, capped at 64 KB. Reported URLs lose their query and fragment, and browser-extension violations are dropped
+- **Models:** `Security::CspViolation` (30-day retention) and `Security::CspViolationReport` (the page's figures)
+- **Database:** a migration in `db/security_migrate` and the `csp_violations` table in `db/security_schema.rb`
+- **Retention:** a daily `purge_csp_violations` task in `config/recurring.yml`
+- **Security page:** a section listing the last 7 days of violations, most frequent first
+- **Policy:** points `report_uri` at the endpoint in `config/initializers/content_security_policy.rb` (no `report-to`, which switches Chrome to the batched Reporting API) and gives anonymous requests a nonce -- Rails' session-id nonce is empty without a session
+- **Rack::Attack:** takes the endpoint out of the general throttle and caps it at 100 reports per 5 minutes per IP
+
+Every step is idempotent. Anything it cannot place safely is listed after the install instead of being forced.
+
+#### Usage
+
+```bash
+rails g maquina:csp_reports
+rails g maquina:csp_reports --path /security/csp-reports   # Different endpoint path
+bin/rails db:migrate
+```
+
+Watch the Security page while the policy is report-only, then set `content_security_policy_report_only = false` to enforce it.
+
+---
+
 ### App -- Full Application Setup (Orchestrator)
 
 **App** is a meta-generator that sets up a complete Rails application in one command. Run it after `rails new myapp --css tailwind`.

data/lib/generators/maquina/clave/clave_generator.rb

@@ -1,5 +1,6 @@
 require "rails/generators"
 require "rails/generators/migration"
+require "active_support/encrypted_configuration"
 
 module Maquina
   module Generators
@@ -42,6 +43,23 @@ module Maquina
       end
 
       # 2. Controllers
+      # EmailVerification encrypts its code, which needs Active Record
+      # encryption keys. They go into the app's credentials when missing; with
+      # no master key to write them, the post-install message says what to run.
+      def configure_encryption_keys
+        credentials = app_credentials
+        if credentials.nil?
+          @encryption_pending = true
+          return
+        end
+
+        content = credentials.read
+        return if content.match?(/^active_record_encryption:/)
+
+        credentials.write(content.rstrip + (content.strip.empty? ? "" : "\n\n") + encryption_keys_yaml)
+        @encryption_written = true
+      end
+
       def create_controllers
         template "app/controllers/concerns/authentication.rb.tt",
           "app/controllers/concerns/authentication.rb"
@@ -172,6 +190,15 @@ module Maquina
           say "  4. Visit /registration/new           # Sign-up page"
         end
         say ""
+        if @encryption_written
+          say "Added Active Record encryption keys to config/credentials.yml.enc (EmailVerification encrypts its code).", :yellow
+          say ""
+        elsif @encryption_pending
+          say "EmailVerification encrypts its code. Generate keys and add them to your credentials:", :yellow
+          say "  bin/rails db:encryption:init"
+          say "  bin/rails credentials:edit"
+          say ""
+        end
         say "Optional:", :yellow
         say "  - Edit app/controllers/concerns/authentication.rb to customize redirect URLs"
         say "  - Edit config/locales/clave.*.yml to customize messages"
@@ -181,6 +208,27 @@ module Maquina
 
       private
 
+      # The app's credentials, or nil when there is no key to decrypt them with.
+      def app_credentials
+        key_path = File.join(destination_root, "config/master.key")
+        return unless File.exist?(key_path) || ENV["RAILS_MASTER_KEY"].present?
+
+        ActiveSupport::EncryptedConfiguration.new(
+          config_path: File.join(destination_root, "config/credentials.yml.enc"),
+          key_path: key_path, env_key: "RAILS_MASTER_KEY", raise_if_missing_key: false
+        )
+      end
+
+      # The same shape `bin/rails db:encryption:init` prints.
+      def encryption_keys_yaml
+        <<~YAML
+          active_record_encryption:
+            primary_key: #{SecureRandom.alphanumeric(32)}
+            deterministic_key: #{SecureRandom.alphanumeric(32)}
+            key_derivation_salt: #{SecureRandom.alphanumeric(32)}
+        YAML
+      end
+
       def migration_version
         "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
       end

data/lib/generators/maquina/clave/templates/app/controllers/registration/verifications_controller.rb.tt

@@ -26,7 +26,16 @@ class Registration::VerificationsController < ApplicationController
       return
     end
 
-    if @verification.code != params[:code]&.upcase&.strip
+    # Too many wrong guesses: kill the code so a fresh one is required.
+    if @verification.locked?
+      @verification.update!(expires_at: Time.current)
+      Rails.logger.warn "[AUTH] Verification locked after #{@verification.attempts} attempts for #{@email} from #{request.remote_ip}"
+      flash.now[:alert] = t("flash.registrations.code_locked")
+      render :new, status: :unprocessable_entity
+      return
+    end
+
+    unless @verification.code_matches?(params[:code])
       @verification.increment!(:attempts)
       Rails.logger.warn "[AUTH] Invalid verification code attempt for #{@email} from #{request.remote_ip} (attempt #{@verification.attempts})"
       flash.now[:alert] = t("flash.registrations.invalid_code")

data/lib/generators/maquina/clave/templates/app/controllers/session/verifications_controller.rb.tt

@@ -27,7 +27,16 @@ class Session::VerificationsController < ApplicationController
       return
     end
 
-    if @verification.code != params[:code]&.upcase&.strip
+    # Too many wrong guesses: kill the code so a fresh one is required.
+    if @verification.locked?
+      @verification.update!(expires_at: Time.current)
+      Rails.logger.warn "[AUTH] Verification locked after #{@verification.attempts} attempts for #{@email} from #{request.remote_ip}"
+      flash.now[:alert] = t("flash.sessions.code_locked")
+      render :new, status: :unprocessable_entity
+      return
+    end
+
+    unless @verification.code_matches?(params[:code])
       @verification.increment!(:attempts)
       Rails.logger.warn "[AUTH] Invalid verification code attempt for #{@email} from #{request.remote_ip} (attempt #{@verification.attempts})"
       flash.now[:alert] = t("flash.sessions.invalid_code")

data/lib/generators/maquina/clave/templates/app/models/email_verification.rb.tt

@@ -1,6 +1,7 @@
 class EmailVerification < ApplicationRecord
   VERIFICATION_TYPES = %w[signup login].freeze
   COOLDOWN_MINUTES = 15
+  MAX_ATTEMPTS = 5
 
   validates :email, presence: true, format: {with: URI::MailTo::EMAIL_REGEXP}
   validates :code, presence: true
@@ -10,6 +11,10 @@ class EmailVerification < ApplicationRecord
   normalizes :email, with: ->(email) { email.strip.downcase }
   normalizes :code, with: ->(code) { code.strip.upcase }
 
+  # Encrypted at rest, not digested: the mail goes out through deliver_later,
+  # whose job reloads this row by GlobalID and must read the code back.
+  encrypts :code
+
   scope :pending, -> { where(verified_at: nil) }
   scope :expired, -> { where("expires_at < ?", Time.current) }
   scope :active, -> { pending.where("expires_at >= ?", Time.current) }
@@ -20,6 +25,19 @@ class EmailVerification < ApplicationRecord
     expires_at < Time.current
   end
 
+  # A code is single-use against a bounded number of guesses: once the wrong-code
+  # count hits the ceiling the record is dead regardless of how many IPs an
+  # attacker rotates through, since each code only ever maps to one row.
+  def locked?
+    attempts >= MAX_ATTEMPTS
+  end
+
+  # Constant-time, so response timing reveals nothing about how close a guess
+  # came. Normalized the same way the stored code is.
+  def code_matches?(candidate)
+    ActiveSupport::SecurityUtils.secure_compare(code, candidate.to_s.strip.upcase)
+  end
+
   def verified?
     verified_at.present?
   end

data/lib/generators/maquina/clave/templates/app/views/sessions/new.html.erb.tt

@@ -30,11 +30,13 @@
           <%%= form.submit t(".submit"), data: { component: "button", variant: "primary" }, class: "w-full px-4 py-3 text-base font-medium text-primary-foreground bg-primary hover:bg-primary/90 rounded-lg transition-colors cursor-pointer" %>
         </div>
       <%% end %>
+<% unless options[:skip_registration] -%>
 
       <p class="mt-6 text-center text-sm text-muted-foreground">
         <%%= t(".no_account") %>
         <%%= link_to t(".sign_up"), new_registration_path, class: "font-medium text-primary hover:text-primary/80" %>
       </p>
+<% end -%>
     </div>
   </div>
 </div>

data/lib/generators/maquina/clave/templates/config/locales/clave.en.yml

@@ -8,6 +8,7 @@ en:
       code_sent: "We sent you a verification code."
       invalid_code: "The code is incorrect. Please try again."
       code_expired: "The code has expired. Request a new one."
+      code_locked: "Too many incorrect tries. Request a new code to keep going."
       code_resent: "We sent you a new code."
       cooldown: "You must wait %{minutes} minutes before requesting another code."
       code_already_sent: "We already sent you a code. Check your email (including spam). You can request a new one in %{minutes} minutes."
@@ -19,6 +20,7 @@ en:
       email_taken: "An account with this email already exists. Would you like to sign in?"
       invalid_code: "The code is incorrect. Please try again."
       code_expired: "The code has expired. Request a new one."
+      code_locked: "Too many incorrect tries. Request a new code to keep going."
       code_resent: "We sent you a new code."
       cooldown: "You must wait %{minutes} minutes before requesting another code."
       code_already_sent: "We already sent you a code. Check your email (including spam). You can request a new one in %{minutes} minutes."

data/lib/generators/maquina/clave/templates/config/locales/clave.es.yml

@@ -8,6 +8,7 @@ es:
       code_sent: "Te enviamos un codigo de verificacion."
       invalid_code: "El codigo es incorrecto. Por favor, intenta de nuevo."
       code_expired: "El codigo ha expirado. Solicita uno nuevo."
+      code_locked: "Demasiados intentos incorrectos. Solicita un codigo nuevo para continuar."
       code_resent: "Te enviamos un nuevo codigo."
       cooldown: "Debes esperar %{minutes} minutos antes de solicitar otro codigo."
       code_already_sent: "Ya te enviamos un codigo. Revisa tu correo (incluyendo spam). Podras solicitar uno nuevo en %{minutes} minutos."
@@ -19,6 +20,7 @@ es:
       email_taken: "Ya existe una cuenta con este correo. Quieres iniciar sesion?"
       invalid_code: "El codigo es incorrecto. Por favor, intenta de nuevo."
       code_expired: "El codigo ha expirado. Solicita uno nuevo."
+      code_locked: "Demasiados intentos incorrectos. Solicita un codigo nuevo para continuar."
       code_resent: "Te enviamos un nuevo codigo."
       cooldown: "Debes esperar %{minutes} minutos antes de solicitar otro codigo."
       code_already_sent: "Ya te enviamos un codigo. Revisa tu correo (incluyendo spam). Podras solicitar uno nuevo en %{minutes} minutos."

data/lib/generators/maquina/csp_reports/USAGE

@@ -0,0 +1,18 @@
+Description:
+  Adds a Content Security Policy violation report endpoint and shows the
+  reports on the backstage Security page. Needs maquina:security, whose
+  `security` database stores them.
+
+  Installs CspReportsController (POST <path>, no session or CSRF, both report
+  formats, 64 KB cap, browser-extension noise dropped), the
+  Security::CspViolation model and its migration in db/security_migrate, the
+  csp_violations table in db/security_schema.rb, a daily purge in
+  config/recurring.yml and a section on the Security page. It points the
+  policy's report-uri at the endpoint, gives anonymous requests a nonce
+  (Rails' session-id nonce is empty without a session), exempts the endpoint
+  from the general Rack::Attack throttle and caps it on its own. Anything it
+  cannot place safely is listed after the install instead of being forced.
+
+Examples:
+  rails g maquina:csp_reports
+  rails g maquina:csp_reports --path /security/csp-reports

data/lib/generators/maquina/csp_reports/csp_reports_generator.rb

@@ -0,0 +1,231 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module Maquina
+  module Generators
+    class CspReportsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      THROTTLE_LIMIT = 100
+      THROTTLE_PERIOD = "5.minutes"
+      # Rails' default nonce generator, empty for a request without a session.
+      SESSION_NONCE = "->(request) { request.session.id.to_s }"
+      POLICY_BLOCK = /^  config\.content_security_policy do \|policy\|\n/
+      # The general throttle's exemptions, in the two shapes maquina:rack_attack
+      # has shipped: a start_with? list, and a STATIC_FILE_PREFIXES word array.
+      COUNTED_IP_EXEMPTIONS = /req\.path\.start_with\?\("\/assets", "\/rails\/active_storage"/
+      STATIC_FILE_PREFIXES = /(STATIC_FILE_PREFIXES = %w\[)([^\]]*)(\])/
+      SECURITY_PAGE_END = /\n<\/div>\n\z/
+
+      class_option :path, type: :string, default: "/csp-reports",
+        desc: "Path browsers post violation reports to"
+      class_option :quiet, type: :boolean, default: false,
+        desc: "Suppress post-install instructions"
+
+      def self.next_migration_number(dirname)
+        current = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        existing = Dir.glob("#{dirname}/[0-9]*_*.rb").map { |f| File.basename(f).split("_", 2).first }.max
+        (existing && existing >= current) ? existing.succ : current
+      end
+
+      # 1. maquina:security owns the database the reports go in.
+      def require_security_database
+        return if File.exist?(File.join(destination_root, "db/security_schema.rb"))
+
+        raise Thor::Error, "maquina:csp_reports stores reports in the `security` database. Run `rails g maquina:security --prefix /admin` first."
+      end
+
+      # 2. Models
+      def create_models
+        copy_file "app/models/security/csp_violation.rb", "app/models/security/csp_violation.rb"
+        copy_file "app/models/security/csp_violation_report.rb", "app/models/security/csp_violation_report.rb"
+      end
+
+      # 3. Controller and route
+      def create_controller
+        copy_file "app/controllers/csp_reports_controller.rb", "app/controllers/csp_reports_controller.rb"
+        route %(post "#{options[:path]}", to: "csp_reports#create", as: :csp_reports)
+      end
+
+      # 4. The table: a migration for an existing security database, the schema
+      #    for a fresh one (db:prepare loads the schema only on create).
+      def create_table
+        return if File.read(schema_path).include?(%("csp_violations"))
+
+        migration_template "db/create_csp_violations.rb.tt", "db/security_migrate/create_csp_violations.rb"
+        version = Dir.glob(File.join(destination_root, "db/security_migrate/*_create_csp_violations.rb"))
+          .map { |f| File.basename(f).split("_", 2).first }.max
+        gsub_file "db/security_schema.rb", /define\(version: [\d_]+\)/, "define(version: #{version_with_underscores(version)})"
+        inject_into_file "db/security_schema.rb", csp_violations_table, before: /^end\s*\z/
+      end
+
+      # 5. The policy reports to the endpoint, and anonymous requests get a nonce.
+      def configure_content_security_policy
+        path = "config/initializers/content_security_policy.rb"
+        content = File.exist?(File.join(destination_root, path)) ? File.read(File.join(destination_root, path)) : ""
+
+        if content.include?("report_uri")
+          @report_uri_pending = !content.include?(%(report_uri "#{options[:path]}"))
+        elsif content.match?(POLICY_BLOCK)
+          inject_into_file path, report_uri_line, after: POLICY_BLOCK
+        else
+          @report_uri_pending = true
+        end
+
+        if content.include?(SESSION_NONCE)
+          gsub_file path, SESSION_NONCE, "->(request) { request.session.id.to_s.presence || SecureRandom.base64(16) }"
+        end
+      end
+
+      # 6. Rack::Attack: out of the general throttle, capped on its own.
+      def configure_rack_attack
+        path = "config/initializers/rack_attack.rb"
+        full_path = File.join(destination_root, path)
+        return @rack_attack_pending = true unless File.exist?(full_path)
+
+        content = File.read(full_path)
+        return if content.include?(%("csp/ip"))
+
+        if content.match?(COUNTED_IP_EXEMPTIONS)
+          # The match stops before the call's closing paren, which stays in place.
+          gsub_file path, COUNTED_IP_EXEMPTIONS, 'req.path.start_with?("/assets", "/rails/active_storage", ' + %("#{options[:path]}")
+        elsif content.match?(STATIC_FILE_PREFIXES)
+          gsub_file path, STATIC_FILE_PREFIXES, "\\1\\2 #{options[:path]}\\3"
+        else
+          @rack_attack_pending = true
+        end
+
+        append_to_file path, csp_throttle
+      end
+
+      # 7. Daily purge
+      def add_recurring_purge
+        path = File.join(destination_root, "config/recurring.yml")
+        content = File.exist?(path) ? File.read(path) : ""
+        return if content.include?("purge_csp_violations")
+
+        if content.match?(/^production:\n/)
+          inject_into_file "config/recurring.yml", recurring_entry, after: /^production:\n/
+        else
+          @recurring_pending = true
+        end
+      end
+
+      # 8. Security page section
+      def add_security_page_section
+        copy_file "app/views/backstage/security/_csp_violations.html.erb",
+          "app/views/backstage/security/_csp_violations.html.erb"
+
+        page = "app/views/backstage/security/show.html.erb"
+        full_path = File.join(destination_root, page)
+        content = File.exist?(full_path) ? File.read(full_path) : ""
+        return if content.include?("backstage/security/csp_violations")
+
+        if content.match?(SECURITY_PAGE_END)
+          inject_into_file page, security_page_section, before: SECURITY_PAGE_END
+        else
+          @page_pending = true
+        end
+      end
+
+      # 9. Post-install message
+      def show_post_install
+        return if options[:quiet]
+
+        say ""
+        say "Content Security Policy reports are set up at POST #{options[:path]}.", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  - Add the table: bin/rails db:migrate (db:prepare on deploy)"
+        say "  - Watch the Security page while the policy is report-only, then set"
+        say "    content_security_policy_report_only = false to enforce it."
+        if @report_uri_pending
+          say ""
+          say "Point the policy at the endpoint in config/initializers/content_security_policy.rb:", :yellow
+          say "  #{report_uri_line.strip}"
+        end
+        if @rack_attack_pending
+          say ""
+          say "Exempt #{options[:path]} from the general throttle in config/initializers/rack_attack.rb and add:", :yellow
+          say csp_throttle
+        end
+        if @recurring_pending
+          say ""
+          say "Add to config/recurring.yml under your production (or shared) key:", :yellow
+          say recurring_entry
+        end
+        if @page_pending
+          say ""
+          say "Render the section on the Security page:", :yellow
+          say security_page_section
+        end
+        say ""
+      end
+
+      private
+
+      def schema_path = File.join(destination_root, "db/security_schema.rb")
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+      def version_with_underscores(version)
+        version.sub(/\A(\d{4})(\d{2})(\d{2})(\d{6})\z/, '\1_\2_\3_\4')
+      end
+
+      def report_uri_line
+        %(    # Violations go to CspReportsController (maquina:csp_reports). report-uri\n) +
+          %(    # alone: adding report-to switches Chrome to the batched Reporting API.\n) +
+          %(    policy.report_uri "#{options[:path]}"\n)
+      end
+
+      def csp_throttle
+        <<~RUBY
+
+          # Content Security Policy reports (maquina:csp_reports): exempt from the
+          # general throttle above — one page with a dozen violations would spend a
+          # reader's budget — and capped on their own.
+          Rack::Attack.throttle("csp/ip", limit: #{THROTTLE_LIMIT}, period: #{THROTTLE_PERIOD}) do |req|
+            (req.env["action_dispatch.remote_ip"]&.to_s || req.ip) if req.path == "#{options[:path]}" && req.post?
+          end
+        RUBY
+      end
+
+      def recurring_entry
+        <<~YAML.gsub(/^/, "  ")
+          purge_csp_violations:
+            command: "Security::CspViolation.expired.delete_all"
+            schedule: every day at 4:30am
+        YAML
+      end
+
+      def security_page_section
+        %(\n\n  <%= render "backstage/security/csp_violations", report: Security::CspViolationReport.new %>)
+      end
+
+      def csp_violations_table
+        <<~RUBY.gsub(/^(?=.)/, "  ")
+
+          create_table "csp_violations", force: :cascade do |t|
+            t.integer "column_number"
+            t.datetime "created_at", null: false
+            t.string "blocked_uri"
+            t.string "disposition"
+            t.string "document_uri"
+            t.string "effective_directive", null: false
+            t.string "ip"
+            t.integer "line_number"
+            t.string "sample"
+            t.string "source_file"
+            t.string "user_agent"
+            t.index ["created_at"], name: "index_csp_violations_on_created_at"
+            t.index ["effective_directive", "created_at"], name: "index_csp_violations_on_effective_directive_and_created_at"
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/maquina/csp_reports/templates/app/controllers/csp_reports_controller.rb

@@ -0,0 +1,24 @@
+# Receives Content Security Policy violation reports. Browsers post them with no
+# cookie and no CSRF token, in either the legacy report-uri shape
+# (application/csp-report) or the Reporting API's (application/reports+json),
+# so this is an API controller that reads the raw body itself.
+#
+# Always 204 for a report it could read — a browser does nothing with the
+# answer — and best effort: a locked security database must never turn a
+# report into a 500 that the browser retries.
+class CspReportsController < ActionController::API
+  MAX_BYTES = 64.kilobytes
+
+  def create
+    body = request.body.read(MAX_BYTES + 1).to_s
+    return head 413 if body.bytesize > MAX_BYTES
+
+    Security::CspViolation.record_report!(body, ip: request.remote_ip, user_agent: request.user_agent)
+    head :no_content
+  rescue JSON::ParserError
+    head :bad_request
+  rescue => error
+    Rails.logger.error "[CSP] report not recorded: #{error.class}: #{error.message}"
+    head :no_content
+  end
+end