trek 2.3.1 → 2.4.0

data/docs/security.md

@@ -0,0 +1,90 @@
+# Security and compliance
+
+ISO 27001 certifies an organization's information security management system, and the NIS2 directive sets obligations for the "essential" and "important" entities of the sectors it lists. Neither applies to a library: using Trek doesn't make an app compliant, and no setting does. What Trek does is provide many of the technical measures these frameworks expect from an application, with defaults chosen for them.
+
+This page lists those measures for an auditor or a security questionnaire, and what stays with the app, its hosting and the organization running it. It describes the current version; measures still to come are marked as planned.
+
+## ISO 27001 controls
+
+The controls of ISO/IEC 27001:2022's Annex A that an application takes part in:
+
+| Control | What Trek provides | Docs |
+| --- | --- | --- |
+| **5.15** Access control, **8.2** Privileged access rights, **8.3** Information access restriction | Roles (`admin`, `editor`…), only `admin` and `editor` can sign in to the admin, and policies authorize each record and attribute per role, only `admin` the audit log | [User › Roles](/reference/models/user#roles), [Policies](/reference/policies) |
+| **5.17** Authentication information | The ANSSI's password recommendations for a privileged access: 12 characters or more, no common password, sequence, name or email; the last 5 passwords refused; optional expiry; an admin can ask everyone for a new password after a suspected compromise. Password reset links last 15 minutes, invitation links a week, and no column stores them | [Password policy](/reference/models/user#password-policy), [Previous passwords](/reference/models/user#previous-passwords) |
+| **5.18** Access rights | Each user's last activity and previous sign-in. Planned: reviewing access, and deactivating dormant accounts | [User › Sign-ins](/reference/models/user#sign-ins) |
+| **5.34** Privacy and protection of PII | The audit log records parameter names, not their values, and the docs set out the GDPR's conditions for keeping it. The breached password check, which would send part of a password's hash to an outside service, is off by default | [Audit log › Personal data](/reference/generators/audit-log#personal-data) |
+| **8.5** Secure authentication | Passkeys, which can't be phished and count as two factors; failed sign-ins throttled per IP address and per account, with an email to the account's user; sign-in and password reset that don't reveal whether an account exists; sessions ending after 48 hours idle and 30 days in all, listed to their user, who can end them; an email on a sign-in from a new browser. Planned: TOTP codes, and requiring a second factor | [User](/reference/models/user#sign-in-and-password-resets) |
+| **8.8** Management of technical vulnerabilities | Generated apps' CI runs Brakeman and bundler-audit, and can make a Software Bill of Materials (SBOM) of their gems and npm packages; Trek's own CI too, and Renovate keeps its dependencies up to date. Planned: a vulnerability disclosure policy | [Installer](/reference/generators/install), [Software Bill of Materials](/reference/generators/install#software-bill-of-materials) |
+| **8.9** Configuration management | The installer gives every app the same configuration, security headers included: a Content Security Policy, report-only at first, and a `Permissions-Policy` turning off the browser features the app doesn't use | [Installer](/reference/generators/install), [Security headers](/reference/generators/security-headers) |
+| **8.15** Logging | An audit log of every change in the admin and every sign-in: author, request, record, status, IP address. Rows can't be changed through the app, and are deleted after 6 months, as the CNIL recommends. Planned: sending them to a store outside the app | [Audit log](/reference/generators/audit-log) |
+| **8.16** Monitoring activities | Errors and performance reported to AppSignal, and the Content Security Policy's violations; users emailed on a sign-in from a new browser and when failed sign-ins lock their account | [Installer](/reference/generators/install) |
+| **8.20** Networks security | The visitor's real IP address behind proxies and CDNs, which the limits and logs rely on; the admin can be restricted to IP addresses and ranges (`ADMIN_ALLOWED_IPS`) | [Proxies](/proxies), [Restricting the admin to IP addresses](/proxies#restricting-the-admin-to-ip-addresses) |
+| **8.24** Use of cryptography | HTTPS only (`force_ssl`, with HSTS and secure cookies), bcrypt password hashes, signed session cookies, signed tokens in emailed links. Planned: encrypting sensitive columns | [Cryptography](#cryptography) |
+| **8.25** to **8.29** Secure development | Trek's changes go through merge requests, with specs, RuboCop, Brakeman and bundler-audit in CI. Generated apps get the same CI, and specs checking Trek's behaviour in them | [Installer](/reference/generators/install) |
+| **8.33** Test information | Planned: anonymized production dumps for development | |
+
+## NIS2 measures
+
+The measures of the directive's Article 21(2), and what Trek provides for each:
+
+| Measure | What Trek provides |
+| --- | --- |
+| (a) Risk analysis and security policies | — |
+| (b) Incident handling | Evidence: the audit log, AppSignal's errors, the sign-in emails |
+| (c) Business continuity, backups, disaster recovery | — |
+| (d) Supply chain security | Dependencies checked for known vulnerabilities in CI (bundler-audit), and kept up to date by Renovate. A CycloneDX [SBOM](/reference/generators/install#software-bill-of-materials) of an app, made in its CI, to hand to a client who asks |
+| (e) Secure development and maintenance, vulnerability handling and disclosure | Changes through merge requests, with specs, RuboCop, Brakeman and bundler-audit in CI; generated apps get the same CI. Planned: a vulnerability disclosure policy |
+| (f) Assessing the measures' effectiveness | — |
+| (g) Cyber hygiene and training | — |
+| (h) Cryptography and encryption | HTTPS only (`force_ssl`, with HSTS and secure cookies), bcrypt password hashes, signed session cookies, signed tokens in emailed links (see [Cryptography](#cryptography)). Planned: encrypting sensitive columns |
+| (i) Human resources security, access control, asset management | Roles, and policies authorizing each record and attribute per role; sessions that expire and that their user can end. Planned: reviewing access, and deactivating dormant accounts |
+| (j) Multi-factor authentication | Passkeys. Planned: TOTP codes, and requiring a second factor |
+
+Measures (a), (c), (f) and (g) are up to the organization and its hosting (see [What Trek expects from the hosting](#what-trek-expects-from-the-hosting)).
+
+Reporting a significant incident (Article 23: an early warning within 24 hours, a notification within 72 hours, a final report within a month) is up to the organization too; the audit log helps establish what happened.
+
+## Cryptography
+
+The cryptography a generated app uses, with Rails 8.1's defaults: an inventory for ISO 27001's control 8.24, and for planning the move to post-quantum cryptography. No tool can make one automatically for a Ruby app, so this inventory is maintained by hand.
+
+| Use | Algorithm | Against a quantum computer |
+| --- | --- | --- |
+| Passwords | bcrypt, cost 12 | Resists |
+| Rails' session cookie (flash messages, CSRF token) | AES-256-GCM | Resists |
+| Signed cookies: the session id, the browsers a user signed in from | HMAC-SHA1 | Resists |
+| Password reset and invitation links (`generates_token_for`) | HMAC-SHA1 | Resists |
+| Keys of the above, derived from `secret_key_base` | PBKDF2-HMAC-SHA256, 1,000 iterations | Resists |
+| Passkeys (the [webauthn](https://github.com/cedarcode/webauthn-ruby) gem's defaults) | ECDSA P-256 (ES256), RSA (PS256, RS256) | Vulnerable, like all of today's public-key signatures; the move depends on browsers and authenticators |
+| Breached password check (off by default) | The first 5 characters of the password's SHA-1, sent to Have I Been Pwned to keep the password unknown to it; not a security function | — |
+| HTTPS | TLS, as configured where it ends (platform router, CDN) | Depends on the hosting |
+| Planned: encrypting sensitive columns | AES-256-GCM (Active Record Encryption) | Resists |
+
+HMAC-SHA1, Rails' default for signed cookies and tokens, isn't broken: an HMAC doesn't rely on SHA-1's collision resistance. The ANSSI advises against SHA-1 in new uses, though, and an audit following its guidance may question it.
+
+## What stays with the app, the hosting and the organization
+
+- **The organization:** its information security management system, risk analysis, policies, training, incident response and reporting, and its suppliers' assessment, the hosting provider's included.
+- **The app:** its own models and controllers, their policies, which data they hold, and keeping Trek and its other dependencies up to date.
+- **The hosting:** backups, redundancy, the network, the servers' security, and its certifications.
+
+## What Trek expects from the hosting
+
+- **Backups** of the database and of the uploads' bucket, encrypted, kept apart from the app, and restored now and then to check them.
+- **HTTPS**, with the proxies in front of the app forwarding the original host, scheme and visitor's IP address (see [Proxies](/proxies)).
+- **A cache store shared** by all the app's processes and servers, for the sign-in limits (see [Failed sign-ins](/reference/models/user#failed-sign-ins)).
+- **An Active Job backend** running the scheduled purges: `Trek::PurgeExpiredSessionsJob`, and `Trek::AuditLog::PurgeJob` with the audit log.
+- **Secrets out of the code:** the master key and API keys in the platform's environment variables, different in each environment.
+- **Logs** kept for a limited time, as they hold IP addresses.
+
+## Recommended settings
+
+For an app whose client is subject to ISO 27001 or NIS2:
+
+- install the [audit log](/reference/generators/audit-log), and schedule its purge;
+- encourage passkeys; for admins signing in with a password only, make it expire after a year (`self.password_expires_after = 1.year`, as the ANSSI suggests);
+- keep the `admin` role to the few people who need it;
+- enforce the Content Security Policy once its reports show no violation left but noise ([Report first, then enforce](/reference/generators/security-headers#report-first-then-enforce));
+- list the CDN's ranges in `trusted_proxies` when there is one ([Proxies](/proxies));
+- when the admins work from known networks (an office, a VPN), restrict the admin to them with `ADMIN_ALLOWED_IPS`.

data/lefthook.yml

@@ -28,8 +28,16 @@ pre-commit:
     prettier:
       tags: css js style
       glob: "{app,config,lib,spec}/**/*.{css,js,json,md,yml}"
+      # The locale files have their own command, as two commands running in parallel on the same
+      # file would clash.
+      exclude: "config/locales/*.yml"
       run: yarn prettier {staged_files} --write
       stage_fixed: true
+    i18n_normalize:
+      tags: i18n style
+      glob: "config/locales/*.yml"
+      run: bundle exec i18n-tasks normalize && yarn prettier {staged_files} --write
+      stage_fixed: true
     slim_lint:
       tags: slim style
       glob: "**/*.slim"

data/lib/generators/trek/install/admin/user_password_resets_generator.rb

@@ -17,6 +17,11 @@ module Trek
               "app/controllers/admin/user_password_resets_controller.rb"
           end
 
+          def copy_job
+            template "jobs/admin/password_reset_job.rb",
+              "app/jobs/admin/password_reset_job.rb"
+          end
+
           def copy_layout
             template "layouts/admin/auth.html.slim",
               "app/views/layouts/admin/auth.html.slim"

data/lib/generators/trek/install/admin/user_sessions_generator.rb

@@ -17,6 +17,11 @@ module Trek
               "app/controllers/admin/user_sessions_controller.rb"
           end
 
+          def copy_passkey_sessions_controller
+            template "controllers/admin/passkey_sessions_controller.rb",
+              "app/controllers/admin/passkey_sessions_controller.rb"
+          end
+
           def copy_layout
             template "layouts/admin/auth.html.slim",
               "app/views/layouts/admin/auth.html.slim"

data/lib/generators/trek/install/admin/users_generator.rb

@@ -13,9 +13,22 @@ module Trek
           source_root File.expand_path("../../templates", __dir__)
 
           def add_routes
+            # A separate route call, so apps installed before get it added rather than their users
+            # block duplicated
+            route <<~RUBY, namespace: :admin
+              resources :active_sessions, only: :destroy do
+                delete :others, action: :destroy_others, on: :collection
+              end
+            RUBY
+            route <<~RUBY, namespace: :admin
+              resources :passkeys, only: %i[create destroy] do
+                get :options, on: :collection
+              end
+            RUBY
             route <<~RUBY, namespace: :admin
               resources :users do
                 patch :theme, on: :collection
+                post :require_password_renewal, on: :collection
               end
             RUBY
           end
@@ -29,6 +42,16 @@ module Trek
             directory "views/admin/users",
               "app/views/admin/users"
           end
+
+          def copy_active_sessions
+            template "controllers/admin/active_sessions_controller.rb",
+              "app/controllers/admin/active_sessions_controller.rb"
+          end
+
+          def copy_passkeys
+            template "controllers/admin/passkeys_controller.rb",
+              "app/controllers/admin/passkeys_controller.rb"
+          end
         end
       end
     end

data/lib/generators/trek/install/audit_log_generator.rb

@@ -0,0 +1,56 @@
+require "rails/generators/actions"
+require "rails/generators/migration"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    module Install
+      class AuditLogGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+        include Trek::Generators::Helpers
+
+        desc "Create the AuditLog model, record the admin's requests, and list them in the admin."
+
+        source_root File.expand_path("../templates", __dir__)
+
+        def copy_model
+          template "models/audit_log.rb", "app/models/audit_log.rb"
+        end
+
+        def copy_migration_file
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/audit_logs.rb.erb",
+            "db/migrate/trek_audit_logs.rb",
+            migration_class_name:)
+        end
+
+        def copy_initializer
+          template "initializers/audit_log.rb", "config/initializers/audit_log.rb"
+        end
+
+        def copy_controller
+          template "controllers/admin/audit_logs_controller.rb",
+            "app/controllers/admin/audit_logs_controller.rb"
+        end
+
+        def copy_views
+          directory "views/admin/audit_logs", "app/views/admin/audit_logs"
+        end
+
+        def copy_policy
+          template "policies/audit_log.rb", "app/policies/admin/audit_log_policy.rb"
+        end
+
+        def add_routes
+          route "resources :audit_logs, only: %i[index show]", namespace: :admin
+        end
+
+        def copy_specs
+          template "spec/models/audit_log_spec.rb", "spec/models/audit_log_spec.rb"
+          template "spec/requests/admin/audit_logs_spec.rb", "spec/requests/admin/audit_logs_spec.rb"
+        end
+      end
+    end
+  end
+end

data/lib/generators/trek/install/authentication_generator.rb

@@ -28,8 +28,8 @@ module Trek
         end
 
         def copy_user_session_model
-          template "models/user_session.rb",
-            "app/models/user_session.rb"
+          template "models/user/session.rb",
+            "app/models/user/session.rb"
         end
 
         def copy_user_sessions_migration
@@ -40,6 +40,64 @@ module Trek
             migration_class_name:)
         end
 
+        def copy_user_previous_password_model
+          template "models/user/previous_password.rb",
+            "app/models/user/previous_password.rb"
+        end
+
+        def copy_user_previous_passwords_migration
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/user_previous_passwords.rb.erb",
+            "db/migrate/trek_user_previous_passwords.rb",
+            migration_class_name:)
+        end
+
+        def copy_user_session_tracking_migration
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/user_session_tracking.rb.erb",
+            "db/migrate/trek_user_session_tracking.rb",
+            migration_class_name:)
+        end
+
+        def copy_user_sign_ins_migration
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/user_sign_ins.rb.erb",
+            "db/migrate/trek_user_sign_ins.rb",
+            migration_class_name:)
+        end
+
+        def copy_user_password_renewal_migration
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/user_password_renewal.rb.erb",
+            "db/migrate/trek_user_password_renewal.rb",
+            migration_class_name:)
+        end
+
+        def copy_user_sign_in_lockout_migration
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/user_sign_in_lockout.rb.erb",
+            "db/migrate/trek_user_sign_in_lockout.rb",
+            migration_class_name:)
+        end
+
+        def copy_user_passkey_model
+          template "models/user/passkey.rb",
+            "app/models/user/passkey.rb"
+        end
+
+        def copy_user_passkeys_migration
+          return unless defined?(ActiveRecord)
+
+          migration_template("migrations/user_passkeys.rb.erb",
+            "db/migrate/trek_user_passkeys.rb",
+            migration_class_name:)
+        end
+
         def inject_authentication_into_user_model
           inject_into_class user_model_path,
             USER_MODEL_CLASS_NAME,
@@ -51,6 +109,11 @@ module Trek
           route "resources :user_password_resets, param: :token, only: %i[new create edit update]", namespace: :admin
           route 'get :login, to: "user_sessions#new", as: :login', namespace: :admin
           route 'delete :logout, to: "user_sessions#destroy", as: :logout', namespace: :admin
+          route <<~RUBY, namespace: :admin
+            resource :passkey_session, only: :create do
+              get :options
+            end
+          RUBY
         end
 
         def autocorrect_user_model
@@ -66,9 +129,20 @@ module Trek
         def user_model_injection
           <<-RUBY
   has_secure_password
+  # Refuses the last 5 passwords; set password_history_size to change it.
+  include Trek::Users::PasswordHistory
+  # Asks for a new password after an admin requires it, or after password_expires_after (none by
+  # default).
+  include Trek::Users::PasswordRenewal
+  # The previous sign-in, and an email on a sign-in from a new browser (new_sign_in_email).
+  include Trek::Users::SignIns
+  # Locks signing in for a while after 5 failed sign-ins in a row, longer on each further failure.
+  include Trek::Users::SignInLockout
+  # Passkeys to sign in with instead of the password (user.passkeys).
+  include Trek::Users::Passkeys
   # Token purposes: :password_reset (15 min) comes from has_secure_password;
   # :invite (1 week) comes from Trek::Users::Invitable.
-  has_many :user_sessions, dependent: :destroy
+  has_many :sessions, dependent: :destroy
 
   scope :privileged, -> { where(role: Trek::Users::Roles::PRIVILEGED_ROLES) }
 

data/lib/generators/trek/install/esbuild_generator.rb

@@ -6,8 +6,7 @@ module Trek
     module Install
       class EsbuildGenerator < Rails::Generators::Base
         NPM_DEPENDENCIES = {
-          esbuild: "^0.15.11",
-          "esbuild-plugin-import-glob": "^0.1.1",
+          esbuild: "^0.28.0",
           "esbuild-rails": "^1.0.3",
           "esbuild-style-plugin": "^1.6.0"
         }

data/lib/generators/trek/install/mailer_generator.rb

@@ -38,6 +38,24 @@ module Trek
           end
         end
 
+        def copy_views_admin_mailer_new_sign_in
+          extensions.each do |extension|
+            locales.each do |lang|
+              template "views/admin_mailer/new_sign_in.#{lang}#{extension}",
+                "app/views/admin_mailer/new_sign_in.#{lang}#{extension}"
+            end
+          end
+        end
+
+        def copy_views_admin_mailer_sign_in_locked
+          extensions.each do |extension|
+            locales.each do |lang|
+              template "views/admin_mailer/sign_in_locked.#{lang}#{extension}",
+                "app/views/admin_mailer/sign_in_locked.#{lang}#{extension}"
+            end
+          end
+        end
+
         def copy_views_passwords_mailer_reset
           extensions.each do |extension|
             locales.each do |lang|

data/lib/generators/trek/install/model_specs_generator.rb

@@ -45,17 +45,19 @@ module Trek
             after: %r{^require ["']rspec/rails["'].*\n}
         end
 
-        # Every file under the templates' db/seeds, spec/models and spec/requests is installed, so a new
+        # Every file under the templates' db/seeds and spec directories is installed, so a new
         # template needs no change here.
         def copy_seeds
           directory "db/seeds", "db/seeds"
         end
 
+        # The audit log's specs come with it, from `trek:install:audit_log`, and the tags' (model and policies) from
+        # `trek:taxonomies`.
         def copy_specs
-          directory "spec/models", "spec/models"
-          directory "spec/requests", "spec/requests"
+          directory "spec/models", "spec/models", exclude_pattern: /audit_log|tag_spec/
+          directory "spec/requests", "spec/requests", exclude_pattern: /audit_log/
+          directory "spec/mailers", "spec/mailers"
           directory "spec/fixtures", "spec/fixtures"
-          # The tag policies' specs come with them, from `trek:taxonomies`.
           directory "spec/policies", "spec/policies", exclude_pattern: /tag(_category)?_policy_spec/
         end
       end

data/lib/generators/trek/install/postcss_generator.rb

@@ -7,14 +7,11 @@ module Trek
       class PostcssGenerator < Rails::Generators::Base
         NPM_DEPENDENCIES = {
           postcss: "^8.4.18",
-          "postcss-cli": "^10.0.0",
           "postcss-flexbugs-fixes": "^5.0.2",
           "postcss-import": "^15.0.0",
           "postcss-inline-svg": "^5.0.0",
           "postcss-modules": "^5.0.0",
-          "postcss-nesting": "^10.2.0",
-          "postcss-preset-env": "^7.8.2",
-          "postcss-url": "^10.1.3"
+          "postcss-preset-env": "^7.8.2"
         }
 
         include Trek::Generators::Helpers

data/lib/generators/trek/install/security_headers_generator.rb

@@ -0,0 +1,49 @@
+require "rails/generators/actions"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    module Install
+      class SecurityHeadersGenerator < Rails::Generators::Base
+        include Trek::Generators::Helpers
+
+        desc "Set up the Content Security Policy (report-only at first) and the Permissions-Policy header."
+
+        source_root File.expand_path("../templates", __dir__)
+
+        def copy_content_security_policy
+          copy_initializer "content_security_policy.rb"
+        end
+
+        def copy_permissions_policy
+          copy_initializer "permissions_policy.rb"
+        end
+
+        # Where browsers send the policy's violations (Trek::CspReportsController)
+        def add_reports_route
+          route 'post "csp-reports", to: "trek/csp_reports#create", as: :csp_reports'
+        end
+
+        private
+
+        # Replaces Rails' commented-out example, but not a policy the app wrote: that one is the app's
+        # to reconcile with Trek's.
+        def copy_initializer(name)
+          path = "config/initializers/#{name}"
+          existing = File.join(destination_root, path)
+
+          if File.exist?(existing) && !commented_out?(existing) && File.read(existing) != File.read(find_in_source_paths("initializers/#{name}"))
+            say_status :skip, "#{path} has the app's own policy: compare it with Trek's (docs: Security headers)", :yellow
+            return
+          end
+
+          template "initializers/#{name}", path, force: true
+        end
+
+        def commented_out?(path)
+          File.readlines(path).all? { |line| line.strip.empty? || line.strip.start_with?("#") }
+        end
+      end
+    end
+  end
+end

data/lib/generators/trek/install/yarn_generator.rb

@@ -5,7 +5,7 @@ module Trek
   module Generators
     module Install
       class YarnGenerator < Rails::Generators::Base
-        YARN_VERSION = "4.18.0"
+        YARN_VERSION = "4.18.1"
 
         include Trek::Generators::Helpers