trek 2.3.1 → 2.4.0

data/docs/reference/environment-variables.md

@@ -3,9 +3,11 @@
 | Variable | Purpose |
 | --- | --- |
 | `ADMIN_EMAIL` / `ADMIN_PASSWORD` | credentials used by [`trek:admin:user`](/reference/generators/admin-user) |
+| `ADMIN_ALLOWED_IPS` | the IP addresses and ranges the admin answers, e.g. `203.0.113.0/24, 2001:db8::/32`; elsewhere it's a 404 (open to all when unset, see [Proxies](/proxies#restricting-the-admin-to-ip-addresses)) |
 | `POSTMARK_API_TOKEN` | Postmark email delivery (auto-injected into credentials by the [installer](/reference/generators/install)) |
 | `APPSIGNAL_PUSH_API_KEY` | AppSignal error tracking and performance monitoring (auto-injected into credentials by the [installer](/reference/generators/install)) |
 | `APPSIGNAL_APP_ENV` | environment name reported to AppSignal (optional, defaults to `RAILS_ENV`) |
 | `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
+| `FEATURE_AUDIT_LOG` | `false` stops the [audit log](/reference/generators/audit-log) recording requests (on by default) |
 | `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
 | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |

data/docs/reference/generators/admin-user.md

@@ -11,7 +11,7 @@ Creates an admin user with the credentials defined by the `ADMIN_EMAIL` and `ADM
 ```sh
 # .env
 ADMIN_EMAIL=admin@example.com
-ADMIN_PASSWORD=a-strong-password
+ADMIN_PASSWORD=
 ```
 
 The created user gets the `admin` [role](/reference/models/user#roles), which makes it `privileged?` and grants it full access in the default [policies](/reference/policies).

data/docs/reference/generators/audit-log.md

@@ -0,0 +1,113 @@
+# Audit log
+
+```sh
+rails g trek:install:audit_log
+bin/rails db:migrate
+```
+
+Records who changed what in the admin, one row per request, and lists the rows to admins. The generator installs:
+
+- the `AuditLog` model, including `Trek::AuditLog`, and its `audit_logs` table
+- `config/initializers/audit_log.rb`, which includes [`Trek::Auditable`](#what-is-recorded) in the admin controllers, the sign-in and the password reset
+- the admin list at `/admin/audit_logs` (controller, views, policy and route), open to the `admin` role only
+- its specs, `spec/models/audit_log_spec.rb` and `spec/requests/admin/audit_logs_spec.rb`
+
+To reach the list from the admin menu, add `AuditLog` to `MODELS_IN_MENU` in `app/models/admin/dashboard.rb`.
+
+## What is recorded
+
+Each mutation (any request but GET and HEAD) writes a row:
+
+| Column | Value |
+| --- | --- |
+| `actor` | `Current.user`, nil when nobody is signed in (a failed sign-in, a request redirected to the sign-in page) |
+| `auditable` | the record the action worked on: `@object` once saved, or once destroyed. For a sign-in, the user signed in to or tried, so an account's failed sign-ins can be listed |
+| `action` | `controller#action`, e.g. `admin/pages#update` |
+| `http_method`, `path`, `http_status` | the request and its response status: a failed sign-in answers 422, a throttled one 429, so both count as failures |
+| `params` | the request's parameter names; their values are replaced with `[FILTERED]`, except for `id` and `role` (see `audit_param_values` below), so the log doesn't copy what the forms send. `config.filter_parameters` (passwords, tokens, emails…) still applies |
+| `ip_address`, `user_agent`, `request_id` | where the request came from |
+| `error_class` | the class of the error the request raised, if any (`http_status` is then nil) |
+
+Rows are append-only: a saved row raises `ActiveRecord::ReadOnlyRecord` when updated. Writing one never breaks the request: a failure is reported through `Rails.error`.
+
+The admin list filters on `action`, `actor_type`/`actor_id` and `auditable_type`/`auditable_id` (e.g. `/admin/audit_logs?filters[auditable_type]=Page&filters[auditable_id]=12`), and lists failures only (an error status or a raised error) with `?scopes[failures]=1`. `Trek::AuditLogsHelper#audit_log_path_for(record)` links to a record's rows, for a button on its admin page.
+
+## Customizing
+
+Include `Trek::Auditable` in any other controller to audit it too, e.g. the front office's `ApplicationController`. Override its hooks there:
+
+```ruby
+class Api::BaseController < ActionController::API
+  include Trek::Auditable
+
+  # Record reads as well as mutations
+  self.audit_reads = true
+
+  # The parameters whose values are recorded, the others by name only (default: id and role)
+  self.audit_param_values = %w[id role status]
+
+  private
+
+  # Who made the request (default: Current.user)
+  def audit_actor = Current.api_client
+
+  # The record the action worked on (default: @object, once saved or destroyed)
+  def audit_target = @order
+
+  # The parameters to record (default: their names, with the values of audit_param_values)
+  def audit_params = super.except("signature")
+
+  # Values for the app's own columns, added by a migration of its own
+  def audit_attributes = { shop_id: Current.shop&.id }
+end
+```
+
+A read showing sensitive data can be recorded explicitly, whatever the HTTP method, with `audit!(name, target)`; the row's action is then `controller#name`:
+
+```ruby
+def show
+  super
+  audit!(:show_medical_record, @object)
+end
+```
+
+## Switching it off
+
+`FEATURE_AUDIT_LOG=false` stops recording, e.g. if writing the rows slows down a busy app. It is read on each request.
+
+## Purging old rows
+
+`Trek::AuditLog::PurgeJob` deletes the rows older than 6 months, the low end of the [CNIL's recommendation](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000044272396) for logs (6 months to 1 year, up to 3 years for a particularly sensitive processing). Schedule it daily with your Active Job backend, e.g. with GoodJob's cron in `config/initializers/good_job.rb`:
+
+```ruby
+Rails.application.configure do
+  config.good_job.enable_cron = true
+  config.good_job.cron = {
+    purge_audit_logs: {
+      cron: "0 4 * * *",
+      class: "Trek::AuditLog::PurgeJob",
+      description: "Delete the audit log rows past the retention window"
+    }
+  }
+end
+```
+
+To keep the rows longer or shorter, set the retention in an initializer: `Trek::AuditLog::PurgeJob.retention = 1.year`.
+
+## Personal data
+
+The rows hold personal data: the author, the IP address, the user agent, and whatever the request's parameters contain. Recording them to secure the app is allowed under the GDPR (its article 32, and recital 49 for people who aren't signed in), on the conditions the [CNIL's recommendation on logs](https://www.legifrance.gouv.fr/jorf/id/JORFTEXT000044272396) sets out:
+
+- **Inform the people recorded**: the admin users (e.g. in their onboarding or the admin's legal notice), and the site's visitors if the front office is audited (its privacy policy): what is recorded, why, and for how long. List the processing in the app's record of processing activities.
+- **Use the rows for security only**: investigating an incident or a misuse, not, for instance, evaluating the people recorded.
+- **Keep them for a limited time**: 6 months to 1 year (see [Purging old rows](#purging-old-rows)).
+- **Limit who reads them**: the list is open to the `admin` role only; keep that role to the few people who need it.
+- **Record no more than needed**: the log keeps the parameters' names, not their values; add a parameter to `audit_param_values` only when its value matters to security (a role, a status), and never one carrying sensitive data such as health data.
+
+## Moving from an app's own audit log
+
+The `audit_logs` table uses the column names of the audit logs some apps wrote themselves (`actor`, `auditable`, `action`, `http_method`, `path`, `http_status`, `params`, `ip_address`, `user_agent`, `request_id`, `error_class`, `created_at`), so existing rows carry over. In such an app, skip the migration and replace the app's own files:
+
+1. Run `rails g trek:install:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
+2. Delete the app's `Auditable` concern, its initializer and its purge job, and update the job's cron entry to `Trek::AuditLog::PurgeJob`.
+3. Move app-specific columns (e.g. a request duration, or a denormalized foreign key) to `audit_attributes`, and their scopes and associations to the `AuditLog` model.

data/docs/reference/generators/install.md

@@ -21,7 +21,7 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 
 | Area | What gets set up |
 | --- | --- |
-| Authentication | bcrypt and `has_secure_password` on `User`, the `UserSession` model (one per signed-in browser, found through a signed `session_id` cookie), the `Trek::Authentication` controller concern, login/logout & password reset panels |
+| Authentication | bcrypt and `has_secure_password` on `User`, the `User::Session` model (one per signed-in browser, found through a signed `session_id` cookie), the `Trek::Authentication` controller concern, login/logout & password reset panels |
 | Authorization | ActionPolicy and the base policies |
 | Models | `User`, `Page`, `PagePath`, `PageVersion`, `Fragment`, `MenuNode`, `ExternalLink`, `Current` — with migrations |
 | Attachments | Shrine configuration and the uploaders |
@@ -31,12 +31,13 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 | Pagination | Kaminari |
 | Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
 | Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
-| Security | Brakeman, bundler-audit, ruby_audit |
+| Security | Brakeman, bundler-audit, ruby_audit; HTTPS only (`force_ssl`, with HSTS), a Content Security Policy and the Permissions-Policy header (`trek:install:security_headers`) — see [Security headers](/reference/generators/security-headers) |
 | Monitoring | AppSignal error tracking and performance monitoring — `config/appsignal.rb`, the push API key in the credentials, and the `AppsignalContext` concern tagging transactions per area and user |
 | Specs | RSpec, and specs for the models Trek installs (`trek:install:model_specs`): `spec/models/page_spec.rb` and `spec/models/user_spec.rb`, with their test data as [Oaken](https://github.com/kaspth/oaken) seed scripts — defaults in `db/seeds/setup/`, scenarios in `db/seeds/test/cases/` loaded with `seed "cases/…"`. They check Trek's behaviour in your app — slugs and paths, user validations and roles — so a customization that breaks it fails your suite; edit or remove the ones you deliberately change. Trek's own suite runs the same files |
 | N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
-| CI | GitLab CI configuration |
+| CI | GitLab CI configuration: specs, linters, Brakeman, bundler-audit, and, commented out, a [Software Bill of Materials](#software-bill-of-materials) |
 | Deployment | Scalingo files (`trek:install:scalingo`, run on demand) — see [Deploying to Scalingo](/deploy) |
+| Audit log | The `AuditLog` model recording the admin's requests, and its admin list (`trek:install:audit_log`, run on demand) — see [Audit log](/reference/generators/audit-log) |
 
 ## ENV variables read by the installer
 
@@ -45,3 +46,11 @@ Define these **before** running the installer to have them injected automaticall
 - `POSTMARK_API_TOKEN` — injected into the Rails credentials for email delivery
 - `APPSIGNAL_PUSH_API_KEY` — injected into the Rails credentials for error tracking and performance monitoring
 - `DEEPL_AUTH_KEY` — enables automatic locale translation in the [scaffold generator](/reference/generators/scaffold)
+
+## Software Bill of Materials
+
+The generated CI has an `sbom` job, commented out: uncomment it when a client asks for an SBOM, as clients subject to NIS2 may. It lists the gems and npm packages of `Gemfile.lock` and `yarn.lock`, with their versions and licenses, in a [CycloneDX](https://cyclonedx.org) file, `sbom.cdx.json`, running [cdxgen](https://github.com/CycloneDX/cdxgen) on every pipeline. GitLab keeps each branch's latest artifacts by default, so the production branch's SBOM can be downloaded from its last pipeline (**Build › Artifacts**).
+
+Looking up the licenses on RubyGems and npm takes a couple of minutes; set `FETCH_LICENSE=false` in the job's command to skip it. The command runs with an empty environment (`env -i`), so cdxgen and the packages `npx` installs for it can't read the CI's tokens and secret variables.
+
+Trek's own CI makes one for each released version, on its tag, and keeps it for good.

data/docs/reference/generators/security-headers.md

@@ -0,0 +1,109 @@
+# Security headers
+
+```bash
+rails g trek:install:security_headers
+```
+
+`rails g trek:install` runs it. It sets up the headers that tell browsers what a page may do, so that a script injected into a page (an XSS) can do as little as possible:
+
+| Header | Set by | Default |
+| --- | --- | --- |
+| `Content-Security-Policy-Report-Only`, then `Content-Security-Policy` | `config/initializers/content_security_policy.rb` | see [below](#content-security-policy) |
+| `Permissions-Policy` | `config/initializers/permissions_policy.rb` | camera, microphone, geolocation, payment, USB… off |
+| `Strict-Transport-Security` | `config.force_ssl` in production, which `trek:install:config` turns on | 2 years, subdomains included |
+| `Referrer-Policy` | Rails | `strict-origin-when-cross-origin`: other sites only see the origin |
+| `X-Content-Type-Options`, `X-Frame-Options` | Rails | `nosniff`, `SAMEORIGIN` |
+
+The headers apply to every response of the app: the admin and the front office alike.
+
+An app with its own `content_security_policy.rb` keeps it: the generator only replaces Rails' commented-out example, and says so otherwise. Compare yours with Trek's below.
+
+## Content Security Policy
+
+| Directive | Sources | Why |
+| --- | --- | --- |
+| `default-src` | `'self'` | anything else comes from the app |
+| `script-src` | `'self'`, the nonce | no inline script, unless written with the nonce (`javascript_tag nonce: true`) |
+| `style-src` | `'self'`, `'unsafe-inline'` | Trek's components and Backpack's set `style` attributes (colors, custom properties) |
+| `font-src` | `'self'`, `data:` | the admin's font, Inter, comes with Trek's npm package |
+| `img-src`, `media-src` | `'self'`, `data:`, `blob:`, the upload hosts | uploads come from `S3_BASE_URL` once stored, and from `S3_ENDPOINT` just after upload; `blob:` and `data:` for previews |
+| `connect-src` | `'self'` | uploads go through the app's upload endpoint |
+| `report-uri` | `/csp-reports` | see [Violation reports](#violation-reports) |
+| `object-src` | `'none'` | no plugin |
+| `frame-ancestors` | `'self'` | framed by its own pages only (Lookbook), against clickjacking |
+| `base-uri`, `form-action` | `'self'` | |
+
+The nonce is the session's, so Turbo, which renders the next pages under the first one's policy, gives their inline scripts a nonce that policy knows. A visitor without a session gets a random one per page: prefer script files to inline scripts on pages Turbo visits before any session.
+
+### Report first, then enforce
+
+The policy only **reports** violations at first (`config.content_security_policy_report_only = true`): a missed source would otherwise break pages. Browse the admin and the front office with the browser's console open, and watch the violations visitors' browsers report (below). Once none is left but noise, set `content_security_policy_report_only` to `false`.
+
+### Violation reports
+
+Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. It logs each one too (`[CSP] script-src-elem blocked https://cdn.example.net on /pages/team (report)`), which is all an app without AppSignal gets.
+
+It keeps the reports about the app's own pages only, and drops what browser extensions load or inject, which makes most reports and says nothing about the app. It keeps the page's path, not its query, which may carry a token, and the blocked resource's origin, not its URL. Browsers send no CSRF token nor cookie: the endpoint needs neither, and answers `204`.
+
+Anyone can send reports, so a flood mustn't bury the real violations:
+
+- a report must be plausible: a directive CSP has, and a keyword (`inline`, `eval`, `data`…) or a host name blocked;
+- AppSignal gets each violation once an hour at most, and 20 different ones an hour at most: the others are only logged;
+- 60 reports a minute per IP address at most, and 600 for all of them together.
+
+These counters are kept in `Rails.cache`: with a cache per process or per server (`:memory_store`, `:file_store`), each counts on its own, so the limits multiply. Use a shared store, such as Solid Cache or Redis, when the app runs more than one.
+
+To send the reports elsewhere, e.g. to a service such as [Report URI](https://report-uri.com), set `CSP_REPORT_URI`. Mind that reports hold visitors' page URLs and IP addresses: under the GDPR, such a service processes personal data for the app.
+
+### Adding a source
+
+Each third party the front office uses needs its hosts, in the directives it uses them for:
+
+```ruby
+# Analytics
+policy.script_src :self, "https://plausible.io"
+policy.connect_src :self, "https://plausible.io"
+
+# Embedded videos
+policy.frame_src "https://www.youtube-nocookie.com"
+
+# Google Fonts (commented out in the generated policy)
+policy.style_src :self, :unsafe_inline, "https://fonts.googleapis.com"
+policy.font_src :self, :data, "https://fonts.gstatic.com"
+```
+
+A directive written twice replaces the first: keep its sources in one call.
+
+Fonts are better served by the app, as Trek does for the admin's with a [Fontsource](https://fontsource.org) package: the policy needs no extra host, and visitors' IP addresses don't go to Google, which the GDPR would require a reason for.
+
+### A policy for one part of the app
+
+A controller can change the policy for its own pages, e.g. to allow videos on the front office's pages only, and its subclasses inherit the change:
+
+```ruby
+class PagesController < ApplicationController
+  content_security_policy do |policy|
+    policy.frame_src "https://www.youtube-nocookie.com"
+  end
+end
+```
+
+The same way, `Admin::BaseController` can tighten the admin's policy, and `content_security_policy_report_only` can keep one part reporting while the rest is enforced.
+
+## Permissions-Policy
+
+Turns off the browser features the app doesn't use: accelerometer, camera, screen capture, geolocation, gyroscope, HID, magnetometer, microphone, MIDI, payment, serial, USB. Passkeys' WebAuthn stays on. To allow one for the app's own pages, e.g. a map locating the visitor, replace `geolocation=()` with `geolocation=(self)`.
+
+Rails' own `config.permissions_policy` still sends the former `Feature-Policy` header, which browsers are dropping: the initializer sets `Permissions-Policy` itself.
+
+## HSTS
+
+`force_ssl` makes browsers use HTTPS only, for 2 years, on subdomains too (`includeSubDomains`). To be preloaded in browsers, so that even the first visit uses HTTPS, add the `preload` flag in `config/environments/production.rb`, then submit the domain on [hstspreload.org](https://hstspreload.org). Every subdomain must serve HTTPS first: preloading is hard to undo.
+
+```ruby
+config.ssl_options = { hsts: { subdomains: true, preload: true } }
+```
+
+## Checking
+
+Once deployed, [Mozilla's HTTP Observatory](https://developer.mozilla.org/en-US/observatory) grades the headers. The report-only policy doesn't count: enforce it to reach an A.

data/docs/reference/index.md

@@ -8,6 +8,8 @@ A comprehensive list of features and settings included in Trek.
 - [Admin user](/reference/generators/admin-user) — `rails g trek:admin:user`
 - [Scaffold](/reference/generators/scaffold) — `rails g trek:scaffold`
 - [Taxonomies](/reference/generators/taxonomies) — `rails g trek:taxonomies`
+- [Audit log](/reference/generators/audit-log) — `rails g trek:install:audit_log`
+- [Security headers](/reference/generators/security-headers) — `rails g trek:install:security_headers`
 
 ## Models
 
@@ -36,6 +38,7 @@ Trek's behaviors, packaged as concerns you can mix into any model:
 - [Formatters](/reference/formatters) — typography & ProseMirror-to-HTML pipeline
 - [Policies](/reference/policies) — ActionPolicy integration
 - [Uploaders](/reference/uploaders) — Shrine-based attachments
+- [Validators](/reference/validators) — disposable email addresses, email format, phone numbers…, for any model
 
 ## Front-end
 

data/docs/reference/models/tag.md

@@ -6,7 +6,7 @@ The taxonomy models, installed by the [taxonomies generator](/reference/generato
 
 | Column | Type | Notes |
 | --- | --- | --- |
-| `key` | string | required, unique within its category |
+| `key` | string | required, unique within its category, or among the tags without one |
 | `name` | string | required display name |
 | `category_id` | bigint | optional [TagCategory](#tagcategory) |
 | `position` | integer | ordering within the category |
@@ -15,6 +15,8 @@ The taxonomy models, installed by the [taxonomies generator](/reference/generato
 - `belongs_to :category`, `has_many :taggings`, and `taggables`, the tagged records of any model
 - Scopes: `ordered`, `in_category(key)`, `in_categories(keys)`
 
+Two categories may share a key: a Colors category and a Fruits category can both have an `orange` tag. The model validates the rule, and the database holds it too, with a unique index on `category_id` and `key`, plus one on `key` for the tags without a category (in a unique index, NULLs never collide).
+
 ## TagCategory
 
 | Column | Type | Notes |
@@ -24,7 +26,7 @@ The taxonomy models, installed by the [taxonomies generator](/reference/generato
 | `position` | integer | ordering |
 | `tags_count` | integer | counter cache |
 
-- `has_many :tags` (ordered)
+- `has_many :tags` (ordered). A category can't be deleted while it has tags: left without a category, their keys could collide with others'. Move or delete them first; the admin says so.
 - Scopes: `ordered`, `with_tags`
 
 ## Tagging

data/docs/reference/models/user.md

@@ -12,8 +12,81 @@ The host application's `User` model, into which Trek injects authentication (`ha
 | `locale` | string | admin UI language |
 | `password_digest` | string | `has_secure_password` (bcrypt), required |
 | `last_activity_at` | datetime | updated after each signed-in admin request |
+| `password_changed_at` | datetime | when the password was last set, for its expiry |
+| `password_renewal_required_at` | datetime | when an admin asked everyone for a new password (`password_renewal_required?`) |
+| `failed_sign_in_count` | integer | failed sign-ins in a row, for the [lockout](#failed-sign-ins) |
+| `sign_in_locked_until` | datetime | until when signing in is locked (`sign_in_locked?`) |
+| `webauthn_id` | string | the random id the user's [passkeys](#passkeys) were created for |
 
-When the app has no `User` model yet, Trek creates the `users` table with its `email` column. Signed-in browsers are `UserSession` records (`user_agent`, `ip_address`) in a `user_sessions` table, found through a signed `session_id` cookie. Password reset (15 minutes) and invitation (1 week) links carry tokens from `generates_token_for`, so no column stores them.
+When the app has no `User` model yet, Trek creates the `users` table with its `email` column. Signed-in browsers are `User::Session` records (`user.sessions`; `user_agent`, `ip_address`) in a `user_sessions` table, found through a signed `session_id` cookie. Password reset (15 minutes) and invitation (1 week) links carry tokens from `generates_token_for`, so no column stores them.
+
+## Sign-in and password resets
+
+Neither tells whether an email has an account, as the [ANSSI recommends](https://messervices.cyber.gouv.fr/guides/recommandations-relatives-lauthentification-multifacteur-et-aux-mots-de-passe) (R14):
+
+- **Sign-in:** an unknown email, a wrong password, a user who isn't privileged and a [locked](#failed-sign-ins) one get the same message and status. `authenticate_by` hashes the password typed even when no user matches, so the response takes as long.
+- **Password reset request:** every email gets the same answer (« a link to choose a new password has been sent to you (unless no account matches this email) »). The request always queues `Admin::PasswordResetJob`, which looks the user up and emails privileged ones only, so the response takes as long either way.
+
+## Failed sign-ins
+
+Password guessing is slowed down at three levels, as the [ANSSI recommends](https://messervices.cyber.gouv.fr/guides/recommandations-relatives-lauthentification-multifacteur-et-aux-mots-de-passe) (R10):
+
+| Limit | Default | Counted in |
+| --- | --- | --- |
+| Sign-ins from an IP address (`rate_limit` in `Admin::UserSessionsController`) | 5 within 3 minutes | `Rails.cache` |
+| Failed sign-ins from an IP address, whatever the account (`FAILED_SIGN_INS_PER_IP`, `FAILED_SIGN_INS_WINDOW`) | 20 within an hour | `Rails.cache` |
+| Failed sign-ins in a row on an account, whatever the IP address (`Trek::Users::SignInLockout`) | 5, then locked | the `users` table |
+
+Past an IP address's limits, the sign-in form answers « Too many attempts » (429) to any sign-in from it.
+
+An account's lock lasts `sign_in_lockout_duration` (1 minute), doubled on each further failure up to `sign_in_lockout_max` (1 hour); never for good, so knowing someone's email isn't enough to keep them out. While locked, signing in fails even with the right password, with the same answer as a wrong one, and the attempts don't count. A successful sign-in or a new password (e.g. through a reset) unlocks it. When it first locks, the user gets an email (`AdminMailer#sign_in_locked`) offering a password reset, and warning that someone may be guessing their password.
+
+Set them in the model, e.g. `self.sign_in_lockout_after = 10`, or `self.sign_in_lockout_email = false` to send no email.
+
+Each sign-in, failed or throttled, is a row of the [audit log](/reference/generators/audit-log) when it is installed, on the account tried.
+
+::: warning Rails.cache
+The IP address limits count in `Rails.cache`. With a cache per process or per server (`:memory_store`, or `:file_store`, Rails' fallback when no store is set), each one counts on its own, so the limits multiply by the number of processes and servers. Use a shared cache store, such as Solid Cache (the default of Rails 8 apps) or Redis, when the app runs more than one. Under `:null_store`, set in a new app's `test.rb`, they never kick in.
+:::
+
+## Sessions
+
+Each signed-in browser is a `User::Session`, which `Trek::Users::SessionLifetime` ends, as the [ANSSI recommends](https://messervices.cyber.gouv.fr/guides/recommandations-relatives-lauthentification-multifacteur-et-aux-mots-de-passe) (R12):
+
+| Setting | Default | |
+| --- | --- | --- |
+| `idle_timeout` | 48 hours | without a request |
+| `lifetime` | 30 days | since signing in, whatever the activity; also the cookie's expiry |
+| `activity_interval` | 5 minutes | the least time between two writes of the session's `last_activity_at` and the user's `last_activity_at`, so browsing doesn't write on every page |
+
+Set them in `app/models/user/session.rb`, e.g. `self.idle_timeout = 2.hours`. An expired session is dropped on its next request, and the user signs in again. `Trek::PurgeExpiredSessionsJob` deletes the expired ones: schedule it daily, e.g. with GoodJob's cron (`class: "Trek::PurgeExpiredSessionsJob"`).
+
+Users see their **active sessions** in a tab of their own profile: browser and system, IP address, last activity and sign-in date. They can sign out any other session, or all of them at once (**Sign out everywhere else**). A password reset signs the user out everywhere.
+
+## Sign-ins
+
+`Trek::Users::SignIns` helps users spot a sign-in that wasn't theirs:
+
+- the **Active sessions** tab of their profile shows their **previous sign-in**: its date, browser and IP address. It's kept on the user (`last_sign_in_at`, `last_sign_in_ip`, `last_sign_in_user_agent`, with their `current_sign_in_*` counterparts), as sessions are deleted when they end;
+- a sign-in from a **browser that never signed in as the user** emails them (`AdminMailer#new_sign_in`): date, browser, IP address, with links to change their password and to their active sessions. A browser is recognized by a signed cookie, kept for years, listing the users who signed in from it. Their very first sign-in sends nothing.
+
+Set `self.new_sign_in_email = false` in the `User` model to turn the email off.
+
+## Passkeys
+
+`Trek::Users::Passkeys` lets users sign in with a passkey instead of their password: their fingerprint, face or device PIN unlocks a key their device or password manager keeps, and Trek keeps its public half. A passkey can't be phished or reused on another site, and the device verifies the user, so it counts as two factors on its own.
+
+- **Adding:** the **Passkeys** tab of their profile adds one (**Add a passkey**): their device creates it, then Trek saves it. The list names each passkey after the password manager keeping it (iCloud Keychain, Google Password Manager, 1Password, a YubiKey…), or else after the browser it was added from, with when it was added and last used; they can delete it there.
+- **Signing in:** the sign-in form offers **Sign in with a passkey**, and the browser also suggests the site's passkeys in the email field's autofill. No email to type: the passkey says whose it is. It works even while [failed passwords](#failed-sign-ins) lock signing in, and lifts that lock, as a passkey can't be guessed.
+- **Password:** it keeps working. Asking for a passkey after the password, as a second factor, will come with TOTP.
+
+Passkeys are `User::Passkey` records (`user.passkeys`, `user_passkeys` table): the credential's id and public key, its signature counter, transports, AAGUID (the id of the authenticator's model, which names its password manager through `Trek::PasskeyProviders`), and `last_used_at`. The user's `webauthn_id`, random, is the id their passkeys were created for. Trek verifies them with the [webauthn](https://github.com/cedarcode/webauthn-ruby) gem, without checking the authenticator's make (no attestation).
+
+A passkey belongs to a domain: Trek uses the request's (`request.host`, with `request.base_url` as the allowed origin), so passkeys work in each environment, with their own. A passkey added on `www.example.com` doesn't work on `example.com`, and behind a proxy, Rails must see the original scheme and host (see [Proxies](/proxies#passkeys)). To share passkeys between subdomains, override `passkey_relying_party` in `Admin::PasskeysController` and `Admin::PasskeySessionsController`, with `id: "example.com"` and every allowed origin.
+
+The password managers' names come from the community list [passkey-authenticator-aaguids](https://github.com/passkeydeveloper/passkey-authenticator-aaguids), names only, embedded in Trek and refreshed with `bin/update-passkey-providers` before a release. An authenticator may send no AAGUID, or one the list doesn't know: the passkey then shows no password manager.
+
+Browsers without WebAuthn's JSON methods (Safari before 18.4) don't show the passkey buttons.
 
 ## Roles
 
@@ -53,7 +126,54 @@ User.create(email: "new@example.com", role: :editor, send_invite: true)
 `Trek::Users::Validations` enforces:
 
 - `email` — stored stripped and in lower case (lookups too, so sign-in and password resets ignore case), present, unique whatever its case, and well-formed by [`email_validator`](https://github.com/K-and-R/email_validator)'s strict mode (no consecutive or leading/trailing dots, a domain with a TLD)
-- `password` — when one is assigned: at least 8 characters, and not spaces only. A blank password is ignored by `has_secure_password` (the current one is kept); the password reset form refuses it
+- `password` — when one is assigned: follows the [password policy](#password-policy), and is not spaces only. A blank password is ignored by `has_secure_password` (the current one is kept); the password reset form refuses it, and not one of the user's last 5 passwords (see [Previous passwords](#previous-passwords))
+
+### Disposable email addresses
+
+Admins create the accounts, so `User` accepts any well-formed address. When users can sign up themselves, refuse throwaway addresses with [`NotDisposableValidator`](/reference/validators#disposable-email-addresses), which any other model can use too:
+
+```ruby
+validates :email, not_disposable: true
+```
+
+## Password policy
+
+`Trek::Users::PasswordPolicy`, which `Trek::Users::Validations` includes, follows the [ANSSI's recommendations on passwords](https://messervices.cyber.gouv.fr/guides/recommandations-relatives-lauthentification-multifacteur-et-aux-mots-de-passe) (v2.0, 2021, co-signed by the CNIL). An admin is privileged access, so Trek targets their **"medium to high"** sensitivity level (about 85 bits of entropy):
+
+| Rule | ANSSI | Default | Setting |
+| --- | --- | --- | --- |
+| Minimum length | R21 | 12 characters | `password_min_length` |
+| A digit and a symbol, except for a passphrase | R23 | below 20 characters | `passphrase_length` |
+| Not a common password, whatever its case, accents and punctuation | R27 | those longer than 8 characters among the 10,000 most common passwords and the 5,000 most common French ones ([SecLists](https://github.com/danielmiessler/SecLists)) | — |
+| No sequence: 5 characters along a keyboard row (AZERTY, QWERTY), the alphabet or the digits, or the same character 5 times | R27 | — | — |
+| Not the user's name or email | R27 | parts of 4 characters or more | — |
+| Not in a known data breach ([Have I Been Pwned](https://haveibeenpwned.com/API/v3#PwnedPasswords)) | R27 | off | `password_check_pwned` |
+| Maximum length | R22 | 72 bytes | — |
+
+Set them in the model, e.g. `self.password_min_length = 15` for the "high" level. The maximum is bcrypt's, which ignores anything beyond: the ANSSI asks for a few hundred characters, which hashing with Argon2 will allow. The Have I Been Pwned check only sends the first 5 characters of the password's SHA-1, but stays off by default, as the ANSSI warns against sending password data to an outside service; when the service can't be reached, the password is accepted.
+
+The new password form states the rules and rates the password as it is typed (`Trek::Form::PasswordStrengthComponent`); the model has the last word.
+
+### Expiry and renewal
+
+`Trek::Users::PasswordRenewal` sends a user to the new password form, signed out, when:
+
+- their password has expired: never by default, as the ANSSI advises for ordinary accounts (R24). For admin accounts signing in with a password only, it suggests 1 to 3 years (R25): `self.password_expires_after = 1.year`;
+- an admin asked everyone for a new password, from the users list (**Ask everyone for a new password**), after a suspected compromise (R26). In code: `User.require_password_renewal!`.
+
+## Previous passwords
+
+`Trek::Users::PasswordHistory` refuses a password among the user's last 5, the current one included, as the [ANSSI recommends](https://messervices.cyber.gouv.fr/guides/recommandations-relatives-lauthentification-multifacteur-et-aux-mots-de-passe) (R27). The previous digests are kept as `User::PreviousPassword` records (`user_previous_passwords` table): only as many as needed, deleted with the user.
+
+Set the number in the model, after `include Trek::Users::PasswordHistory`; 0 turns the check off:
+
+```ruby
+class User < ApplicationRecord
+  has_secure_password
+  include Trek::Users::PasswordHistory
+  self.password_history_size = 10
+end
+```
 
 ## Scopes
 
@@ -63,5 +183,5 @@ User.create(email: "new@example.com", role: :editor, send_invite: true)
 
 Two non-persisted `ActiveModel::Model` companions handle the auth flows:
 
-- **`Trek::UserSession`** — `email` + `password`, used by the login form
+- **`Trek::UserSession`** — `email` + `password` typed in a sign-in form. Deprecated, removed in Trek 3: the generated sign-in controller passes the params to `User.authenticate_by` instead
 - **`Trek::UserPasswordReset`** — `email`, looks up the `user` to send a reset link to

data/docs/reference/validators.md

@@ -0,0 +1,94 @@
+# Validators
+
+Validators available to any Active Record or Active Model class of the app (`User`, a sign-up, a contact or newsletter form…): Trek's own, and those of the gems Trek depends on, which it loads.
+
+| Validator | Key | From |
+| --- | --- | --- |
+| [Disposable email addresses](#disposable-email-addresses) | `not_disposable` | Trek |
+| [Email format](#email-format) | `email` | [email_validator](https://github.com/K-and-R/email_validator) |
+| [Email checks](#email-checks) | `"valid_email_2/email"` | [valid_email2](https://github.com/micke/valid_email2) |
+| [Phone numbers](#phone-numbers) | `phone` | [Phonelib](https://github.com/daddyz/phonelib) |
+| [Uniqueness of a translated attribute](#uniqueness-of-a-translated-attribute) | `uniqueness` | [Mobility](https://github.com/shioyama/mobility) |
+
+## Disposable email addresses
+
+`NotDisposableValidator` refuses an email address from a throwaway email provider (mailinator.com, yopmail.com…), or a subdomain of one, whatever its case:
+
+```ruby
+class Contact < ApplicationRecord
+  validates :email, presence: true, email: { mode: :strict }, not_disposable: true
+end
+```
+
+It is opt-in: Trek doesn't add it to `User`, whose accounts admins create. A blank address is left to the presence validation.
+
+The error is `:disposable`, « is a disposable email address, use a permanent one » (« est une adresse e-mail jetable, utilisez-en une permanente »). Change it in the app's locales (`errors.messages.disposable`), or per model:
+
+```ruby
+validates :email, not_disposable: { message: "must be your work address" }
+```
+
+The domains come from the [valid_email2](https://github.com/micke/valid_email2) gem, whose maintainers keep the list up to date: updating the gem updates the list, with no data to refresh in the app. Only the list is checked, without looking up the domain's mail servers. To let a domain through, list it in `config/allow_listed_email_domains.yml`:
+
+```yaml
+- legit-provider.example
+```
+
+The list (about 180,000 domains) is loaded on the first check, as a single string of 2.6 MB searched by bisection, rather than valid_email2's own Set of about 35 MB: about 5 µs per address.
+
+## Email format
+
+`EmailValidator` checks an address's shape, without any network lookup:
+
+```ruby
+validates :email, email: { mode: :strict }
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `mode` | `:loose` | `:loose` only asks for something on each side of an `@`; `:strict` refuses consecutive or leading/trailing dots and asks for a domain with a TLD; `:rfc` follows RFC 5322 |
+| `require_fqdn` | — (true in `:strict` mode) | a domain with a TLD |
+| `domain` | — | only this domain, e.g. `domain: "example.com"` |
+| `allow_nil` | `false` | |
+
+`User` uses `:strict` mode.
+
+## Email checks
+
+valid_email2's validator checks an address's shape too, and optionally more: its domain's mail servers (`mx: true`, `strict_mx: true`), a deny list (`deny_list: true`, from `config/deny_listed_email_domains.yml`), or refusing `+tag` addresses (`disallow_subaddressing: true`). See [its options](https://github.com/micke/valid_email2#usage).
+
+```ruby
+validates :email, "valid_email_2/email": { mx: true }
+```
+
+- `mx` and `strict_mx` look the domain up in the DNS on every validation, which can take up to `dns_timeout` (5 seconds) and fails offline, in specs too.
+- For disposable addresses, use [`not_disposable`](#disposable-email-addresses) rather than its `disposable` options: they load its Set of 180,000 domains, which grows each process by about 35 MB.
+
+## Phone numbers
+
+`PhoneValidator` checks a phone number with Phonelib, against `Phonelib.default_country` when the number has no country code:
+
+```ruby
+validates :phone, phone: { possible: true, allow_blank: true }
+```
+
+| Option | |
+| --- | --- |
+| `possible` | `true` to only ask whether the digits could form a number for the country; otherwise they must fall in a range actually assigned (see [Strictness](/reference/concerns/phonable#strictness)) |
+| `types` | e.g. `:mobile`, `[:mobile, :fixed]` |
+| `countries` | e.g. `[:fr, :be]` |
+| `allow_blank` | a blank value fails otherwise |
+
+[`Trek::Phonable`](/reference/concerns/phonable) adds it for you, with the number's normalization and formatting.
+
+## Uniqueness of a translated attribute
+
+On a model with [translated attributes](/reference/concerns/translatable), Mobility replaces `uniqueness`, so it works on them too, in the current locale: a title taken in English is still free in French.
+
+```ruby
+class Fragment < ApplicationRecord
+  include Trek::Translatable
+  translate_attributes :title, :content
+  validates :title, uniqueness: true
+end
+```