maquina-generators 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79618453431401c828cd9f89037c0111810fe7ff1b3328986fb99fea3282e010
-  data.tar.gz: e33ebfe0accac9a78432b1548648fce1ca8de0176370673f84665a7928eefeef
+  metadata.gz: 3a31ee05a1ed941cc88119c5721629c3c5089081dde3e7833d1768cb9598b202
+  data.tar.gz: 5bc0462a7009085c8a752791090347501a59886cab23eb74ba7bdd5ff0ff2f08
 SHA512:
-  metadata.gz: c5c84a544b6295a6dfd32833b8d65febdb7e9d1de3e79da20c67e55cc7d5102c585a61b76f640ae3eb01cd1e59a57172c7930a90ea86f47bbcf7e49583709cf6
-  data.tar.gz: 27361ba6b7f8c51778eee636c43715ce8aa6dcce88c5a6c929c4715d4980b27db240fdbaba8139b3859d920976ad8fc1655881cf965c891099063c63cf88b635
+  metadata.gz: 85c73f484e3ed4e09e28ec2bebf42ca13ea1dd84693b9e7abbffa0746f14aa69930d95607c0c592085ad6acd88ba2a5d81afd90e602c8265cf9122e05d86a3ef
+  data.tar.gz: bf4cec22c128729f8425b71d345a6ef166e6c9f4d18172860ef1eca3bbb894997397ce227297168f54218d6d26c87dc707dbedbd7b268594620543d22f1b6437

data/README.md

@@ -19,12 +19,14 @@ 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:
 
 ```ruby
-gem "maquina_generators", group: :development
+gem "maquina-generators", group: :development
 ```
 
 Run the generator:
@@ -55,6 +57,7 @@ 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`
@@ -114,8 +117,10 @@ All generated code lives in your app -- edit it directly:
 
 - **BackstageController:** Inherits from `ActionController::Base` (bypasses app's ApplicationController concerns)
 - **Initializer:** Credentials-first auth with ENV variable fallback, database connection config
-- **Route:** Mounts `SolidErrors::Engine` under a configurable prefix
-- **Admin navigation:** Shared navigation bar linking Solid Errors and Mission Control Jobs dashboards
+- **Route:** Mounts `SolidErrors::Engine` at `<prefix>/errors`
+- **Mailer templates:** Self-contained `error_occurred` HTML and text templates, so `send_emails` works without the dashboard's helpers
+- **Admin navigation:** Shared navigation bar with Overview, Errors, Jobs and Security tabs
+- **Admin overview:** `BackstageDashboardController` at the prefix root with cards for each installed dashboard and a `@metrics` slot for your own aggregate counts; answers 503 until backstage credentials are set
 - **Custom layout:** Tailwind-styled layout with admin navigation and toast flash messages
 - **Stimulus controllers:** `clipboard_controller.js` and `backtrace_filter_controller.js`
 - **Custom views:** Tailwind-styled views to override the gem defaults (included by default, use `--no-copy-views` to skip)
@@ -156,8 +161,9 @@ Credentials are resolved in order:
 - **BackstageController:** Inherits from `ActionController::Base` with maquina_components helpers (bypasses app's ApplicationController concerns)
 - **Helper:** `MissionControlHelper` with `job_status_badge_variant` and `nav_icon_for_section`
 - **Initializer:** Sets base controller class, credentials-first auth with ENV variable fallback
-- **Route:** Mounts `MissionControl::Jobs::Engine` under a configurable prefix
-- **Admin navigation:** Shared navigation bar linking Solid Errors and Mission Control Jobs dashboards
+- **Route:** Mounts `MissionControl::Jobs::Engine` at `<prefix>/jobs`
+- **Admin navigation:** Shared navigation bar with Overview, Errors, Jobs and Security tabs
+- **Admin overview:** `BackstageDashboardController` at the prefix root with cards for each installed dashboard and a `@metrics` slot for your own aggregate counts; answers 503 until backstage credentials are set
 - **Custom layout:** Tailwind-styled layout with admin navigation, toast flash messages, application/server selection, and tab navigation
 - **Custom views:** Tailwind-styled views for jobs, queues, workers, and recurring tasks (included by default, use `--no-copy-views` to skip)
 
@@ -218,28 +224,132 @@ rails g maquina:solid_queue --database postgresql # PostgreSQL
 
 ### Rack Attack -- Request Protection
 
-**Rack Attack** installs the [rack-attack](https://github.com/rack/rack-attack) gem with default security rules to block common vulnerability scans and throttle abusive requests.
+**Rack Attack** installs the [rack-attack](https://github.com/rack/rack-attack) gem with rules that ban vulnerability scanners and addresses that ignore the throttle.
 
 #### What it generates
 
-- **Initializer:** `config/initializers/rack_attack.rb` with blocklists, safelists, and throttles
+- **Initializer:** `config/initializers/rack_attack.rb` with the bans, throttles, safelist, 403 responder and an `[ATTACK]` log line per refusal. Its knobs are constants on `Rack::Attack` (`SCANNER_*`, `GENERAL_*`, `FLOOD_*`, `LOGIN_*`) and `Rack::Attack.banned?(ip)` answers whether an address is banned now.
 
 #### Usage
 
 ```bash
 rails g maquina:rack_attack
+rails g maquina:rack_attack --login-path /sign_in   # Throttle a different sign-in path
 ```
 
 The generator automatically runs `bundle install`.
 
 #### Default Protections
 
-- **Blocklists:** PHP files (`*.php`), WordPress paths (`wp-admin`, `wp-login`, etc.), sensitive files (`.env`, `.git`, `/etc/passwd`, etc.), scanner targets (`phpmyadmin`, `cgi-bin`, etc.)
+- **Scanner ban (Fail2Ban):** three scanner paths in 10 minutes bans the IP for 7 days. Scanner paths are PHP files (`*.php`), WordPress paths (`wp-admin`, `wp-login`, etc.), sensitive files anywhere in the path (`.env`, `.git`, `/etc/passwd`, etc.), backup archives (`.zip`, `.sql`, `.tar.gz`, `.bak`, etc.) and scanner targets (`phpmyadmin`, `cgi-bin`, etc.). `/rails/active_storage` is exempt.
+- **Flood ban (Allow2Ban):** 600 requests in 5 minutes (twice the general throttle) bans the IP for 1 day.
+- **Throttles:** 300 requests/5min per IP (general; `/assets` and `/rails/active_storage` exempt), 5 `POST /session`/20s per IP
 - **Safelists:** Localhost (`127.0.0.1`, `::1`)
-- **Throttles:** 300 requests/5min per IP (general), 5 login attempts/20s per IP
-- **Responses:** 403 Forbidden for blocklisted, 429 Too Many Requests for throttled
+- **Responses:** 403 Forbidden for blocklisted and banned, 429 Too Many Requests for throttled
+
+Bans live in `Rails.cache`, so they need a shared cache store (Solid Cache) in production. Customize rules in `config/initializers/rack_attack.rb`. To see the refusals, add `maquina:security`.
+
+---
+
+### Security -- Rack::Attack with an Abuse Dashboard
+
+**Security** records every Rack::Attack refusal in its own database and summarises the last week on a backstage page next to Solid Errors and Mission Control Jobs.
+
+#### What it generates
+
+- **Rack::Attack rules:** runs `maquina:rack_attack` unless `config/initializers/rack_attack.rb` already defines `Rack::Attack.banned?` (an older initializer without it is replaced)
+- **Subscriber:** `config/initializers/rack_attack_events.rb` writes a `Security::AbuseEvent` per throttled, blocked or banned request; a failed write never turns a 403 into a 500
+- **Models:** `Security::Record` (`connects_to` the `security` database), `Security::AbuseEvent` (30-day retention), `Security::AbuseReport` (the page's figures)
+- **Database:** `db/security_schema.rb` and a `security:` entry in every multi-database environment of `config/database.yml` (and `config/database.yml.example`)
+- **Retention:** a daily `purge_abuse_events` task in `config/recurring.yml`
+- **BackstageController**, **controller** (`Backstage::SecurityController`), **route** (`<prefix>/security`), **layout** and **views**: stats, throttled addresses, blocked addresses (banned now, expired or not yet banned), scanner paths, sign-in throttles, targeted hosts, refusals by day, recent refusals (views skipped with `--no-copy-views`)
+- **Admin navigation:** a Security tab, added to an existing `_admin_navigation` partial too
+- **Admin overview:** the shared dashboard at the prefix root, if Solid Errors or Mission Control Jobs have not installed it already
+
+#### What the page shows
+
+The last 7 days of refusals, top five of each, read from `Security::AbuseEvent` through `Security::AbuseReport`. It is a briefing, not a log viewer: no filters, no pagination. Times are UTC.
+
+- **Stats:** refused requests, throttled, blocked or banned, and distinct addresses
+- **Throttled addresses:** over the general or sign-in limit, busiest first, with the rules they hit
+- **Blocked addresses:** every address a blocklist refused, marked **Banned now** (Rack::Attack's own answer at render time), **Expired**, or **Not banned** -- an address with a strike or two on the scanner rule, or a slow scanner that stays under three paths in ten minutes
+- **Most requested blocked paths:** what the scanners were after. A banned address is refused on every path, its ordinary pages included, so only the paths `Rack::Attack.scanner_path?` recognises are listed
+- **Sign-in throttles:** addresses refused on `POST <login-path>`, kept apart so scanner noise never buries them
+- **Targeted hosts:** which hostnames the refusals were aimed at
+- **By day:** throttled, blocked and banned per day, zeros kept so a spike reads against its neighbours
+- **Recent refusals:** the last 20, newest first
+
+#### Usage
+
+```bash
+rails g maquina:security --prefix /admin
+bin/rails db:prepare
+```
+
+The generator automatically runs `bundle install`. The page needs maquina_components.
+
+#### Options
+
+```bash
+rails g maquina:security --prefix /admin                      # Default
+rails g maquina:security --prefix /admin --login-path /sign_in  # Different sign-in path
+rails g maquina:security --prefix /admin --no-copy-views      # Without views
+rails g maquina:security --prefix /backstage \
+  --user-env-var ADMIN_USER --password-env-var ADMIN_PASSWORD  # Custom env vars
+```
+
+#### Authentication
+
+HTTP Basic Auth, with credentials resolved in order:
+
+1. `Rails.application.credentials.backstage.username` / `.password`
+2. `ENV["SECURITY_USER"]` / `ENV["SECURITY_PASSWORD"]` (configurable)
+
+The page answers 503 until one of them is set, so it is never left open.
+
+#### Trying it locally
+
+Localhost is safelisted, so your own requests are never refused. Rack::Attack trusts `X-Forwarded-For` from `127.0.0.1`, so send one to stand in for another address:
+
+```bash
+for path in /wp-login.php /.env /backup.zip /; do
+  curl -s -o /dev/null -w "%{http_code} $path\n" -H "X-Forwarded-For: 203.0.113.10" http://localhost:3000$path
+done
+# 403 /wp-login.php
+# 403 /.env
+# 403 /backup.zip   <- third scanner path: banned for 7 days
+# 403 /             <- banned, so every path is refused
+```
+
+Development's `:memory_store` keeps bans inside the server process, so they reset on restart and a `bin/rails runner` script cannot see them. Production needs a shared store (Solid Cache).
+
+---
+
+### 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
+```
 
-Customize rules in `config/initializers/rack_attack.rb`.
+Watch the Security page while the policy is report-only, then set `content_security_policy_report_only = false` to enforce it.
 
 ---
 
@@ -259,10 +369,10 @@ Customize rules in `config/initializers/rack_attack.rb`.
 8. Sets up ActiveStorage JavaScript imports
 9. Adds turbo morphing, `yield :head`, and simplifies `<main>` tag in layout
 10. Optionally installs authentication (`maquina:clave` or `maquina:registration`)
-11. Invokes sub-generators: `maquina:rack_attack`, `maquina:mission_control_jobs`, `maquina:solid_errors`
-12. Runs external installers: `solid_queue:install`, `solid_errors:install`, `solid_cache:install`, `solid_cable:install`, `maquina_components:install`
+11. Invokes sub-generators: `maquina:mission_control_jobs`, `maquina:solid_errors`
+12. Runs external installers: `solid_queue:install`, `solid_errors:install`, `solid_cache:install`, `solid_cable:install`, `maquina_components:install`, then `maquina:security` (which installs the `maquina:rack_attack` rules)
 13. Restores custom layouts overwritten by gem installers
-14. Configures multi-database `database.yml` (primary, queue, cache, cable, errors)
+14. Configures multi-database `database.yml` (primary, queue, cache, cable, errors, security)
 15. Creates a HomeController with root route
 16. Generates a README and `database.yml.example`
 17. Runs `db:prepare`
@@ -277,7 +387,7 @@ rails g maquina:app --auth registration
 
 #### Options
 
-- `--prefix` (default: `/admin`) -- Base path prefix for backstage tools (Solid Errors, Mission Control Jobs)
+- `--prefix` (default: `/admin`) -- Base path prefix for backstage tools (Solid Errors, Mission Control Jobs, Security)
 - `--port` (default: `3000`) -- Default port for the development server
 - `--auth` (default: `none`) -- Authentication type: `none`, `clave`, or `registration`
 

data/lib/generators/maquina/app/app_generator.rb

@@ -199,7 +199,6 @@ module Maquina
       def install_maquina_generators
         return unless rails_app?
 
-        generate "maquina:rack_attack", "--quiet"
         generate "maquina:mission_control_jobs", "--prefix", options[:prefix], "--quiet"
         generate "maquina:solid_errors", "--prefix", options[:prefix], "--quiet"
 
@@ -210,6 +209,10 @@ module Maquina
           system("bin/rails generate solid_cable:install", chdir: destination_root)
           system("bin/rails generate maquina_components:install", chdir: destination_root)
         end
+
+        # After solid_queue:install, so config/recurring.yml exists for the purge.
+        # Installs the maquina:rack_attack rules too.
+        generate "maquina:security", "--prefix", options[:prefix], "--quiet"
       end
 
       # 13. Restore custom layouts overwritten by gem installers
@@ -323,10 +326,12 @@ module Maquina
         say "  2. Start the app: bin/dev"
         say ""
         say "Installed components:", :yellow
-        say "  - Rack::Attack: rate limiting and blocklists (config/initializers/rack_attack.rb)"
+        say "  - Rack::Attack: scanner and flood bans, throttles (config/initializers/rack_attack.rb)"
+        say "  - Security: Rack::Attack refusals at #{options[:prefix]}/security"
         say "  - Solid Queue: background jobs (config/solid_queue.yml)"
-        say "  - Mission Control Jobs: job dashboard at #{options[:prefix]}/mission_control_jobs"
-        say "  - Solid Errors: error tracking at #{options[:prefix]}/solid_errors"
+        say "  - Mission Control Jobs: job dashboard at #{options[:prefix]}/jobs"
+        say "  - Solid Errors: error tracking at #{options[:prefix]}/errors"
+        say "  - Admin overview: #{options[:prefix]}"
         say "  - Maquina Components: UI components"
         if options[:auth] != "none"
           say ""

data/lib/generators/maquina/app/templates/README.md.erb

@@ -34,15 +34,17 @@ Your app will be running at **http://localhost:<%= options[:port] %>**.
 | **WebSockets** | Solid Cable |
 | **Rich Text** | Action Text |
 | **File Storage** | Active Storage (S3-ready in production) |
-| **Multi-database** | Separate databases for queue, cache, cable, and errors |
+| **Multi-database** | Separate databases for queue, cache, cable, errors, and security |
 
 ## Development URLs
 
 | URL | Description |
 |-----|-------------|
 | http://localhost:<%= options[:port] %> | Application |
-| http://localhost:<%= options[:port] %><%= options[:prefix] %>/mission_control_jobs | Jobs dashboard |
-| http://localhost:<%= options[:port] %><%= options[:prefix] %>/solid_errors | Errors dashboard |
+| http://localhost:<%= options[:port] %><%= options[:prefix] %> | Admin overview |
+| http://localhost:<%= options[:port] %><%= options[:prefix] %>/errors | Errors dashboard |
+| http://localhost:<%= options[:port] %><%= options[:prefix] %>/jobs | Jobs dashboard |
+| http://localhost:<%= options[:port] %><%= options[:prefix] %>/security | Security dashboard |
 <% if options[:auth] != "none" -%>
 | http://localhost:<%= options[:port] %>/session/new | Sign in |
 <% if options[:auth] == "registration" -%>
@@ -65,7 +67,7 @@ Edit credentials with:
 bin/rails credentials:edit
 ```
 
-Add backstage credentials for the jobs and errors dashboards:
+Add backstage credentials for the admin dashboards (overview, errors, jobs, security):
 
 ```yaml
 backstage:

data/lib/generators/maquina/app/templates/app/views/home/index.html.erb

@@ -32,17 +32,17 @@
 <%% if authenticated? %>
   <section class="max-w-5xl mx-auto px-5 py-12">
     <p class="text-sm font-semibold uppercase tracking-wider text-primary mb-4">Admin Tools</p>
-    <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
       <%%= render "components/card" do %>
         <%%= render "components/card/header" do %>
           <div class="flex items-center gap-2">
-            <%%= icon_for(:activity, class: "size-5 text-primary") %>
+            <%%= icon_for(:triangle_alert, class: "size-5 text-primary") %>
             <%%= render "components/card/title", text: "Solid Errors" %>
           </div>
           <%%= render "components/card/description", text: "Browse, resolve, and clean up application exceptions in real time." %>
         <%% end %>
         <%%= render "components/card/footer" do %>
-          <%%= link_to "Open Dashboard", "<%= options[:prefix] %>/solid_errors", data: { component: "button", variant: "outline", size: "sm" } %>
+          <%%= link_to "Open Dashboard", "<%= options[:prefix] %>/errors", data: { component: "button", variant: "outline", size: "sm" } %>
         <%% end %>
       <%% end %>
 
@@ -55,7 +55,20 @@
           <%%= render "components/card/description", text: "Monitor queues, retry failed jobs, and manage background processing." %>
         <%% end %>
         <%%= render "components/card/footer" do %>
-          <%%= link_to "Open Dashboard", "<%= options[:prefix] %>/mission_control_jobs", data: { component: "button", variant: "outline", size: "sm" } %>
+          <%%= link_to "Open Dashboard", "<%= options[:prefix] %>/jobs", data: { component: "button", variant: "outline", size: "sm" } %>
+        <%% end %>
+      <%% end %>
+
+      <%%= render "components/card" do %>
+        <%%= render "components/card/header" do %>
+          <div class="flex items-center gap-2">
+            <%%= icon_for(:slash, class: "size-5 text-primary") %>
+            <%%= render "components/card/title", text: "Security" %>
+          </div>
+          <%%= render "components/card/description", text: "See what Rack::Attack throttled, blocked, and banned this week." %>
+        <%% end %>
+        <%%= render "components/card/footer" do %>
+          <%%= link_to "Open Dashboard", "<%= options[:prefix] %>/security", data: { component: "button", variant: "outline", size: "sm" } %>
         <%% end %>
       <%% end %>
     </div>
@@ -109,7 +122,7 @@
         <%%= render "components/card/title", text: "Rate Limiting" %>
       <%% end %>
       <%%= render "components/card/content" do %>
-        <p class="text-sm text-muted-foreground">Rack::Attack configured with blocklists and throttles. Protect login, registration, and API endpoints.</p>
+        <p class="text-sm text-muted-foreground">Rack::Attack bans scanners and floods and throttles sign-in. Every refusal shows on the Security dashboard.</p>
       <%% end %>
     <%% end %>
 

data/lib/generators/maquina/app/templates/config/database.yml.tt

@@ -29,6 +29,10 @@ development:
     <<: *default
     database: storage/development_errors.sqlite3
     migrations_paths: db/errors_migrate
+  security:
+    <<: *default
+    database: storage/development_security.sqlite3
+    migrations_paths: db/security_migrate
 
 # Warning: The database defined as "test" will be erased and
 # re-generated from your development database when you run "rake".
@@ -53,6 +57,10 @@ test:
     <<: *default
     database: storage/test_errors.sqlite3
     migrations_paths: db/errors_migrate
+  security:
+    <<: *default
+    database: storage/test_security.sqlite3
+    migrations_paths: db/security_migrate
 
 # Store production database in the storage/ directory, which by default
 # is mounted as a persistent Docker volume in config/deploy.yml.
@@ -76,3 +84,7 @@ production:
     <<: *default
     database: storage/production_errors.sqlite3
     migrations_paths: db/errors_migrate
+  security:
+    <<: *default
+    database: storage/production_security.sqlite3
+    migrations_paths: db/security_migrate

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/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