trek 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. checksums.yaml +4 -4
  2. data/AGENTS.md +12 -11
  3. data/CHANGELOG.md +51 -0
  4. data/Gemfile.lock +124 -126
  5. data/Makefile +7 -1
  6. data/README.md +17 -21
  7. data/app/components/trek/form/content_editor_component/content_editor_component.css +4 -8
  8. data/app/components/trek/form/image_field_component/image_field_component.js +1 -2
  9. data/app/components/trek/form/password_strength_component/password_strength_component.css +2 -0
  10. data/app/components/trek/form/sound_field_component/sound_field_component.js +1 -2
  11. data/app/components/trek/security_check_component/security_check_component.css +69 -0
  12. data/app/components/trek/security_check_component/security_check_component.html.slim +19 -0
  13. data/app/components/trek/security_check_component/security_check_component.js +15 -0
  14. data/app/components/trek/security_check_component.rb +19 -0
  15. data/app/content/trek/content/cleaner.rb +1 -1
  16. data/app/content/trek/content/list_item.rb +1 -1
  17. data/app/content/trek/content/paragraph.rb +7 -2
  18. data/app/controllers/concerns/trek/auditable.rb +5 -2
  19. data/app/controllers/concerns/trek/localization.rb +6 -2
  20. data/app/jobs/trek/purge_expired_sign_in_codes_job.rb +15 -0
  21. data/app/policies/trek/security_check_policy.rb +8 -0
  22. data/app/uploaders/image_uploader.rb +77 -15
  23. data/config/locales/trek.en.yml +71 -0
  24. data/config/locales/trek.fr.yml +71 -0
  25. data/docs/.vitepress/config.mjs +1 -0
  26. data/docs/background-jobs.md +10 -5
  27. data/docs/deploy.md +69 -6
  28. data/docs/getting-started.md +15 -17
  29. data/docs/index.md +1 -1
  30. data/docs/personal-data.md +61 -0
  31. data/docs/proxies.md +2 -2
  32. data/docs/reference/components.md +2 -2
  33. data/docs/reference/concerns/fragmentable.md +12 -6
  34. data/docs/reference/concerns/orderable.md +2 -2
  35. data/docs/reference/concerns/search-engine-optimizable.md +1 -1
  36. data/docs/reference/concerns/searchable.md +14 -1
  37. data/docs/reference/concerns/sectionable.md +7 -3
  38. data/docs/reference/concerns/versionable.md +1 -1
  39. data/docs/reference/controllers.md +33 -1
  40. data/docs/reference/environment-variables.md +2 -2
  41. data/docs/reference/formatters.md +2 -1
  42. data/docs/reference/forms.md +6 -3
  43. data/docs/reference/generators/admin-user.md +1 -1
  44. data/docs/reference/generators/audit-log.md +12 -13
  45. data/docs/reference/generators/install.md +20 -9
  46. data/docs/reference/generators/public-accounts.md +21 -3
  47. data/docs/reference/generators/scaffold.md +28 -9
  48. data/docs/reference/generators/security-headers.md +4 -3
  49. data/docs/reference/generators/taxonomies.md +1 -1
  50. data/docs/reference/icons.md +5 -3
  51. data/docs/reference/index.md +10 -8
  52. data/docs/reference/models/current.md +5 -3
  53. data/docs/reference/models/page-version.md +1 -1
  54. data/docs/reference/models/user.md +5 -8
  55. data/docs/reference/uploaders.md +25 -0
  56. data/docs/reference/validators.md +1 -1
  57. data/docs/security.md +30 -9
  58. data/docs/what-is-trek.md +3 -3
  59. data/lib/generators/trek/USAGE +1 -1
  60. data/lib/generators/trek/audit_log_generator.rb +8 -0
  61. data/lib/generators/trek/helpers.rb +17 -0
  62. data/lib/generators/trek/install/admin/routes_generator.rb +2 -1
  63. data/lib/generators/trek/install/admin/security_check_generator.rb +36 -0
  64. data/lib/generators/trek/install/ci_generator.rb +19 -0
  65. data/lib/generators/trek/install/postcss_generator.rb +1 -2
  66. data/lib/generators/trek/install/translations_generator.rb +1 -2
  67. data/lib/generators/trek/install_generator.rb +8 -7
  68. data/lib/generators/trek/public_accounts_generator.rb +34 -7
  69. data/lib/generators/trek/scaffold_generator.rb +22 -21
  70. data/lib/generators/trek/scalingo_generator.rb +13 -1
  71. data/lib/generators/trek/templates/.gitlab-ci.yml +10 -1
  72. data/lib/generators/trek/templates/AGENTS.md +2 -2
  73. data/lib/generators/trek/templates/Makefile +1 -0
  74. data/lib/generators/trek/templates/config/i18n-tasks.yml.erb +0 -8
  75. data/lib/generators/trek/templates/controllers/admin/security_checks_controller.rb +11 -0
  76. data/lib/generators/trek/templates/controllers/concerns/trek/authentication.rb +13 -4
  77. data/lib/generators/trek/templates/initializers/good_job.rb.tt +7 -5
  78. data/lib/generators/trek/templates/layouts/admin.html.slim +5 -0
  79. data/lib/generators/trek/templates/policies/security_check.rb +4 -0
  80. data/lib/generators/trek/templates/public_accounts/api/controllers/sessions_controller.rb.tt +13 -1
  81. data/lib/generators/trek/templates/public_accounts/api/controllers/sign_in_codes_controller.rb.tt +5 -0
  82. data/lib/generators/trek/templates/public_accounts/jobs/sign_in_code_job.rb.tt +10 -0
  83. data/lib/generators/trek/templates/public_accounts/locales/accounts.en.yml.tt +10 -0
  84. data/lib/generators/trek/templates/public_accounts/locales/accounts.fr.yml.tt +10 -0
  85. data/lib/generators/trek/templates/public_accounts/models/account.rb.tt +16 -2
  86. data/lib/generators/trek/templates/public_accounts/spec/api/sign_ins_spec.rb.tt +30 -0
  87. data/lib/generators/trek/templates/public_accounts/spec/models/account/sign_in_code_spec.rb.tt +10 -0
  88. data/lib/generators/trek/templates/public_accounts/spec/models/account_spec.rb.tt +21 -1
  89. data/lib/generators/trek/templates/public_accounts/spec/web/sign_ins_spec.rb.tt +22 -0
  90. data/lib/generators/trek/templates/public_accounts/web/authentication.rb.tt +1 -1
  91. data/lib/generators/trek/templates/public_accounts/web/controllers/sessions_controller.rb.tt +8 -1
  92. data/lib/generators/trek/templates/public_accounts/web/controllers/sign_in_codes_controller.rb.tt +5 -0
  93. data/lib/generators/trek/templates/public_accounts/web/views/password_resets/edit.html.slim.tt +4 -1
  94. data/lib/generators/trek/templates/public_accounts/web/views/passwords/edit.html.slim.tt +4 -1
  95. data/lib/generators/trek/templates/public_accounts/web/views/registrations/new.html.slim.tt +3 -1
  96. data/lib/generators/trek/templates/public_accounts/web/views/sessions/new.html.slim.tt +3 -1
  97. data/lib/generators/trek/templates/spec/requests/admin/pages_spec.rb +11 -0
  98. data/lib/generators/trek/templates/spec/requests/admin/security_checks_spec.rb +24 -0
  99. data/lib/generators/trek/templates/spec/requests/admin/sign_in_notices_spec.rb +33 -0
  100. data/lib/generators/trek/templates/views/admin/pages/_form.html.slim +1 -1
  101. data/lib/generators/trek/templates/views/admin/security_checks/show.html.slim +9 -0
  102. data/lib/generators/trek/templates/views/admin/user_password_resets/edit.html.slim +6 -1
  103. data/lib/generators/trek/templates/views/admin/user_sessions/new.html.slim +4 -1
  104. data/lib/tasks/trek/attachments.rake +12 -0
  105. data/lib/tasks/trek/security.rake +10 -0
  106. data/lib/trek/disposable_email_domains.rb +9 -20
  107. data/lib/trek/engine.rb +5 -0
  108. data/lib/trek/json_compatibility.rb +20 -0
  109. data/lib/trek/security_check.rb +241 -0
  110. data/lib/trek/stored_image_metadata.rb +88 -0
  111. data/lib/trek/version.rb +1 -1
  112. data/lib/trek.rb +2 -1
  113. data/package.json +5 -6
  114. data/postcss.config.js +0 -3
  115. data/trek.gemspec +5 -6
  116. data/yarn.lock +983 -1042
  117. metadata +33 -31
@@ -1,7 +1,7 @@
1
1
  # Installer
2
2
 
3
3
  ```sh
4
- rails g trek:install
4
+ bin/rails g trek:install
5
5
  # or (soon)
6
6
  trek install
7
7
  ```
@@ -19,7 +19,7 @@ It ends with what to do next: create an admin user, start the server, and the ge
19
19
 
20
20
  ## Sub-generators
21
21
 
22
- The installer orchestrates dedicated sub-generators, all under the `trek:install:*` namespace. Each one can also be run individually, e.g. `rails g trek:install:healthcheck`.
22
+ The installer orchestrates dedicated sub-generators, all under the `trek:install:*` namespace. Each one can also be run individually, e.g. `bin/rails g trek:install:healthcheck`.
23
23
 
24
24
  | Area | What gets set up |
25
25
  | --- | --- |
@@ -27,18 +27,18 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
27
27
  | Authorization | ActionPolicy and the base policies |
28
28
  | Models | `User`, `Page`, `PagePath`, `PageVersion`, `Fragment`, `MenuNode`, `ExternalLink`, `Current` — with migrations |
29
29
  | Attachments | Shrine configuration and the uploaders |
30
- | Emails | Postmark and the user mailer |
30
+ | Emails | Postmark, `AdminMailer` (invitations, new sign-in and lockout alerts) and `Admin::PasswordsMailer` (password resets) |
31
31
  | I18n | rails-i18n, Mobility, i18n-tasks and the locale files |
32
- | Admin panels | Pages, fragments, users, sessions, password resets, routes, dashboard |
32
+ | Admin panels | Pages, fragments, users, sessions, password resets, routes, dashboard, and a [Security](/security#in-the-admin) page for admins |
33
33
  | Pagination | Kaminari |
34
34
  | Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
35
- | Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
36
- | 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) |
35
+ | Linting | RuboCop (rubocop-rails-omakase and rubocop-rspec), ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
36
+ | Security | Brakeman, bundler-audit, [`yarn npm audit`](#vulnerable-dependencies); 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) |
37
37
  | Jobs | GoodJob as the Active Job backend, replacing Solid Queue — dashboard at `/admin/good_job`, cron in `config/initializers/good_job.rb`, pool sized by `GOOD_JOB_MAX_THREADS` — see [Background jobs](/background-jobs) |
38
38
  | 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 |
39
- | 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 |
39
+ | Specs | RSpec, and specs for what Trek installs (`trek:install:model_specs`): its models (`spec/models/page_spec.rb`, `spec/models/user_spec.rb`…), the admin's requests, policies and mailers, 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 |
40
40
  | N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
41
- | CI | GitLab CI configuration: specs, linters, Brakeman, bundler-audit, and, commented out, a [Software Bill of Materials](#software-bill-of-materials) |
41
+ | CI | GitLab CI configuration: specs, linters, Brakeman, bundler-audit, [`yarn npm audit`](#vulnerable-dependencies), and, commented out, a [Software Bill of Materials](#software-bill-of-materials) |
42
42
 
43
43
  ## ENV variables read by the installer
44
44
 
@@ -46,7 +46,18 @@ Define these **before** running the installer to have them injected automaticall
46
46
 
47
47
  - `POSTMARK_API_TOKEN` — injected into the Rails credentials for email delivery
48
48
  - `APPSIGNAL_PUSH_API_KEY` — injected into the Rails credentials for error tracking and performance monitoring
49
- - `DEEPL_AUTH_KEY` — enables automatic locale translation in the [scaffold generator](/reference/generators/scaffold)
49
+
50
+ ## Vulnerable dependencies
51
+
52
+ `make scan` and the generated CI check the app's dependencies for known vulnerabilities: the gems of `Gemfile.lock` with [bundler-audit](https://github.com/rubysec/bundler-audit) (`bundler-audit` job), the npm packages of `yarn.lock` with `yarn npm audit` (`npm-audit` job). Like bundler-audit, the npm check fails on any advisory, whatever its severity, and also on a deprecated package, which no longer gets security fixes. It only checks the packages the app bundles (`dependencies`, with their own): an advisory on a build or lint tool (`devDependencies`) doesn't block a deploy.
53
+
54
+ To fix a vulnerable gem, `make audit-fix` updates it, commits and pushes. For an npm package:
55
+
56
+ - `yarn why <package>` shows which dependency brings it in.
57
+ - `yarn up -R <package>` moves it to the latest version its dependents allow; a direct dependency goes to a fixed version with `yarn up <package>@<version>`.
58
+ - When a dependent pins a vulnerable range, a [`resolutions`](https://yarnpkg.com/configuration/manifest#resolutions) entry in `package.json` forces a fixed version, e.g. `"resolutions": { "nanoid@^4.0.0": "^5.1.16" }`, once you've checked the dependent works with it. Remove it when the dependent catches up.
59
+ - A deprecated package is replaced by the one its notice names, or upgraded past the deprecated version.
60
+ - An advisory that doesn't apply to the app (code it never reaches), or a deprecation that can't be fixed yet, can be skipped: add its ID to `npmAuditIgnoreAdvisories` in `.yarnrc.yml`, with a comment saying why. The ID is the number `yarn npm audit` shows, or `<package> (deprecation)` for a deprecation.
50
61
 
51
62
  ## Software Bill of Materials
52
63
 
@@ -1,7 +1,7 @@
1
1
  # Public accounts
2
2
 
3
3
  ```sh
4
- rails g trek:public_accounts Customer [--sign-in=code|password] [--api] [--path=customers] [--model-only]
4
+ bin/rails g trek:public_accounts Customer [--sign-in=code|password] [--invite-only] [--api] [--path=customers] [--model-only]
5
5
  bin/rails db:migrate
6
6
  ```
7
7
 
@@ -12,6 +12,7 @@ The name is required, and is the app's own: `User` is the admin's account, so th
12
12
  | Option | Effect |
13
13
  | --- | --- |
14
14
  | `--sign-in=code` (default) | Accounts sign in with a code emailed to them, which creates the account the first time: there is no password, nor sign-up form |
15
+ | `--invite-only` | With codes: only the accounts the app created sign in, and signing in never creates one. See [Invite only](#invite-only) |
15
16
  | `--sign-in=password` | Accounts sign up with an email and a password, confirm the email by a link, and reset a forgotten password by one: there are no codes |
16
17
  | `--api` | A mobile app: JSON endpoints under `/api/v1`, and a session held through a JWT, with no pages. Without it, a website: pages, and a session kept in a cookie |
17
18
  | `--path=customers` | Puts the routes under a path, e.g. `/customers/sign-in`: for an app with two kinds of public accounts |
@@ -32,6 +33,12 @@ A code is valid for 10 minutes, for 5 tries (the right one included), and once.
32
33
 
33
34
  A new email address is confirmed the same way: a code sent to it.
34
35
 
36
+ ### Invite only
37
+
38
+ With `--invite-only`, signing in is no longer signing up: only the accounts the app created sign in (from an admin panel, an invitation…), for a private site such as a client portal or an intranet. Asking for a code still answers the same for every email, "If ada@example.com has an account, a code has just been sent to it", but `Customers::SignInCodeJob` sends a code only to an email that has an account, so the form doesn't tell who has one, neither by its answer nor by its timing. A code then signs in to that account, and never creates one.
39
+
40
+ Which accounts may sign in is `Customer.for_sign_in(email)`, `find_by(email:)` by default: narrow it to let only some in, e.g. `active.find_by(email:)`. Both the job and the sign-in use it.
41
+
35
42
  ## Signing in with a password
36
43
 
37
44
  - **Signing up** takes an email and a password, following the same rules as the admin's (`Trek::Users::PasswordPolicy`: 12 characters, a digit and a symbol below 20…, configurable), and signs in at once. A link confirming the email is sent, valid a day; following it sets `confirmed_at`. The app decides what an unconfirmed account may do (`customer.confirmed?`), and the account page sends the link again.
@@ -56,7 +63,18 @@ Both are `Customer::Session` rows (`customer_sessions`), listed on the account,
56
63
 
57
64
  Deleting the account, and changing the password, need a sign-in less than 15 minutes old; otherwise the website sends the person to sign in again, and the API answers 403 with `recent_sign_in_needed`.
58
65
 
59
- Schedule the purge of expired sessions daily, as for the admin's: `Trek::PurgeExpiredSessionsJob.perform_later("Customer::Session")`.
66
+ The generator schedules the purge of expired sessions every night in GoodJob's cron, as for the admin's (`Trek::PurgeExpiredSessionsJob` with `args: ["Customer::Session"]`). With another Active Job backend, it says so, and the purge is to schedule daily: `Trek::PurgeExpiredSessionsJob.perform_later("Customer::Session")`.
67
+
68
+ With codes, it also schedules the purge of expired codes, which each hold an email (`Trek::PurgeExpiredSignInCodesJob` with `args: ["Customer::SignInCode"]`, at 3:45am): a new code deletes the expired ones too, but nothing would delete the last ones requested. An app generated before it adds the entry to its `config.good_job.cron` by hand:
69
+
70
+ ```ruby
71
+ purge_expired_customer_sign_in_codes: {
72
+ cron: "45 3 * * *",
73
+ class: "Trek::PurgeExpiredSignInCodesJob",
74
+ args: ["Customer::SignInCode"],
75
+ description: "Delete the customer sign-in codes past their validity"
76
+ },
77
+ ```
60
78
 
61
79
  The admin's own session (`session_id`, `User::Session`) is untouched: someone may be signed in to both, as two accounts that can share an email address.
62
80
 
@@ -133,7 +151,7 @@ The generated files are the app's own: upgrading Trek never changes them. On eac
133
151
  - **The generator's own changes,** a security fix among them, which reach the app only by running it again. On a clean working tree, run it with the same name and options, then review `git diff` and restore the app's own changes:
134
152
 
135
153
  ```sh
136
- rails g trek:public_accounts Customer --force # plus the options it was generated with
154
+ bin/rails g trek:public_accounts Customer --force # plus the options it was generated with
137
155
  git diff
138
156
  ```
139
157
 
@@ -1,7 +1,8 @@
1
1
  # Scaffold
2
2
 
3
3
  ```sh
4
- rails g trek:scaffold Book title intro:text
4
+ bin/rails g trek:scaffold Book title intro:text
5
+ bin/rails db:migrate
5
6
  ```
6
7
 
7
8
  Akin to Rails', Trek's scaffold generates, with a single command:
@@ -10,40 +11,58 @@ Akin to Rails', Trek's scaffold generates, with a single command:
10
11
  - the `Admin::BooksController`, inheriting from [`Trek::ResourceController`](/reference/controllers)
11
12
  - the Slim views: `index`, `show`, `new`, `edit` and the `_form` partial
12
13
  - the `Admin::BookPolicy`, inheriting from [`Trek::ResourcePolicy`](/reference/policies)
13
- - the `resources :books` route in the `admin` namespace
14
- - the locale files for the model and its admin panel, in every configured locale (auto-translated via DeepL when `DEEPL_AUTH_KEY` is set)
14
+ - the `resources :books, except: :show` route in the `admin` namespace, with a commented-out `reorder` route (the `show` view is generated all the same, for when you add the route)
15
+ - the locale files for the model and its admin panel, in every configured locale
15
16
  - the entry in the admin dashboard menu
16
17
 
17
18
  ## Field types
18
19
 
19
- Standard Rails attribute types are supported (`string`, `text`, `integer`, `float`, `decimal`, `boolean`, `date`, `datetime`, `references`…) and mapped to the matching [form helpers](/reference/forms): `text` renders the content editor, `boolean` a switch box, `references` a collection select, and so on.
20
+ Standard Rails attribute types are supported (`string`, `text`, `integer`, `float`, `decimal`, `boolean`, `date`, `datetime`, `references`…). Each field gets the form helper Rails' own scaffold picks: `text_field` for a `string`, `textarea` for a `text`, `checkbox` for a `boolean`, a `text_field` of the id for a `references`, and so on. Swap them in the generated `_form` for Trek's [form helpers](/reference/forms) where they fit: `content_editor` for rich text, `switch_box`, a `collection_select`…
20
21
 
21
22
  ## Namespaced models
22
23
 
23
24
  ```sh
24
- rails g trek:scaffold Shop::Product name price:decimal
25
+ bin/rails g trek:scaffold Shop::Product name price:decimal
25
26
  ```
26
27
 
27
28
  The controller and policy are nested accordingly (`Admin::Shop::ProductsController`, `Admin::Shop::ProductPolicy`), the routes go under `namespace :shop`, and everything else follows the namespace.
28
29
 
29
30
  The generated code references the model as `::Shop::Product`, top-level qualified, and the dashboard menu entry is `::Shop::Product` too. This is deliberate: once `Admin::Shop` exists, a bare `Shop` written anywhere under `module Admin` resolves to that namespace instead of the `Shop` model. Existing admin code that references such a model — an `Admin::ShopsController#model` returning `Shop`, or a `Shop` entry in `Admin::Dashboard::MODELS_IN_MENU` — must be updated to `::Shop` once a scaffold introduces a namespace with the same name (the menu would otherwise silently list the module).
30
31
 
31
- Also note that `rails g model Shop::Product` (which the scaffold runs) writes `app/models/shop.rb` as a `module Shop` namespace file; if a `Shop` model already lives there, the generator warns and Rails asks before overwriting it — move the model or answer `n`.
32
+ Also note that `bin/rails g model Shop::Product` (which the scaffold runs) writes `app/models/shop.rb` as a `module Shop` namespace file; if a `Shop` model already lives there, the generator warns and Rails asks before overwriting it — move the model or answer `n`.
32
33
 
33
- ## Opt-in concerns
34
+ ## The model
34
35
 
35
- The generated model ships with commented-out hooks for Trek's most useful [concerns](/reference/), ready to be enabled when needed:
36
+ The admin shows a record by its `to_s`, in lists and titles: the scaffold returns the first `string` attribute given (here `title`), or Ruby's default (`#<Book:0x…>`) when it's blank. Without a `string` attribute, `to_s` is left to write.
37
+
38
+ The generated model ships with commented-out hooks for Trek's most useful [concerns](/reference/), ready to be enabled when needed, each under a `TODO`:
36
39
 
37
40
  ```ruby
38
41
  class Book < ApplicationRecord
42
+ # TODO: uncomment to format some attributes, or remove if not needed
39
43
  # include Trek::Formattable
40
44
  # format_attributes Trek::TypographyFormatter, :title
41
45
 
46
+ # TODO: uncomment to translate some attributes, or remove if not needed
42
47
  # include Trek::Translatable
43
48
  # translate_attributes :title
44
49
 
45
- # include RecordImageUploader::Attachment(:image)
50
+ # TODO: choose how the model should be ordered in the admin panel
51
+ # scope :ordered, -> { order(:id) }
46
52
 
47
53
  strip_attributes
54
+
55
+ # TODO: uncomment to attach files to the model, or remove if not needed
56
+ # include RecordImageUploader::Attachment(:image)
57
+
58
+ # The title in the admin panel
59
+ def to_s
60
+ title.presence || super
61
+ end
62
+
63
+ # TODO: choose which attribute to use as image in the admin panel, or remove if not needed
64
+ # def image
65
+ # image_url || super
66
+ # end
48
67
  end
49
68
  ```
@@ -1,10 +1,10 @@
1
1
  # Security headers
2
2
 
3
3
  ```bash
4
- rails g trek:install:security_headers
4
+ bin/rails g trek:install:security_headers
5
5
  ```
6
6
 
7
- `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:
7
+ `bin/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:
8
8
 
9
9
  | Header | Set by | Default |
10
10
  | --- | --- | --- |
@@ -26,7 +26,8 @@ An app with its own `content_security_policy.rb` keeps it: the generator only re
26
26
  | `script-src` | `'self'`, the nonce | no inline script, unless written with the nonce (`javascript_tag nonce: true`) |
27
27
  | `style-src` | `'self'`, `'unsafe-inline'` | Trek's components and Backpack's set `style` attributes (colors, custom properties) |
28
28
  | `font-src` | `'self'`, `data:` | the admin's font, Inter, comes with Trek's npm package |
29
- | `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 |
29
+ | `img-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 |
30
+ | `media-src` | `'self'`, `blob:`, the upload hosts | the same, without `data:` |
30
31
  | `connect-src` | `'self'` | uploads go through the app's upload endpoint |
31
32
  | `report-uri` | `/csp-reports` | see [Violation reports](#violation-reports) |
32
33
  | `object-src` | `'none'` | no plugin |
@@ -1,7 +1,7 @@
1
1
  # Taxonomies
2
2
 
3
3
  ```sh
4
- rails g trek:taxonomies
4
+ bin/rails g trek:taxonomies
5
5
  ```
6
6
 
7
7
  Sets up a tagging & categorization system:
@@ -1,11 +1,13 @@
1
1
  # Icons
2
2
 
3
- Trek bundles ~40 SVG icons, rendered with `Trek::IconComponent`:
3
+ Trek bundles ~40 SVG icons, rendered with `Trek::IconComponent`. A key is the icon's path under `app/assets/icons/`, so Trek's own are prefixed with `trek/`:
4
4
 
5
5
  ```ruby
6
- render Trek::IconComponent.new(:search)
6
+ render Trek::IconComponent.new("trek/search")
7
7
  ```
8
8
 
9
- Available keys include: `add`, `arrow-bar-left`, `arrow-bar-right`, `bold`, `check`, `chevron-left`, `chevron-right`, `chevron-double`, `close`, `cursor`, `danger`, `download`, `eraser`, `external`, `eye`, `grid`, `hr`, `italic`, `layout`, `link`, `list`, `logout`, `paragraph`, `pic`, `profile`, `quotation`, `rating`, `redo`, `undo`, `search`…
9
+ An app's own icons, in its `app/assets/icons/`, are rendered by their name alone (`IconComponent.new("logo")` for `app/assets/icons/logo.svg`).
10
+
11
+ Trek's keys include: `add`, `arrow-bar-left`, `arrow-bar-right`, `bold`, `check`, `chevron-left`, `chevron-right`, `chevron-double-left`, `chevron-double-right`, `close`, `cursor`, `danger`, `download`, `eraser`, `external`, `eye`, `grid`, `hr`, `italic`, `layout`, `link`, `list`, `logout`, `paragraph`, `pic`, `profile`, `quotation`, `rating`, `redo`, `undo`, `search`…
10
12
 
11
13
  [MenuNode](/reference/models/menu-node) records can reference an icon via their `icon_key` to display it in the admin sidebar.
@@ -4,13 +4,15 @@ A comprehensive list of features and settings included in Trek.
4
4
 
5
5
  ## Generators
6
6
 
7
- - [Installer](/reference/generators/install) — `rails g trek:install`
8
- - [Admin user](/reference/generators/admin-user) — `rails g trek:admin:user`
9
- - [Scaffold](/reference/generators/scaffold) — `rails g trek:scaffold`
10
- - [Taxonomies](/reference/generators/taxonomies) — `rails g trek:taxonomies`
11
- - [Audit log](/reference/generators/audit-log) — `rails g trek:audit_log`
12
- - [Public accounts](/reference/generators/public-accounts) — `rails g trek:public_accounts`
13
- - [Security headers](/reference/generators/security-headers) — `rails g trek:install:security_headers`
7
+ - [Installer](/reference/generators/install) — `bin/rails g trek:install`
8
+ - [Admin user](/reference/generators/admin-user) — `bin/rails g trek:admin:user`
9
+ - [Scaffold](/reference/generators/scaffold) — `bin/rails g trek:scaffold`
10
+ - [Taxonomies](/reference/generators/taxonomies) — `bin/rails g trek:taxonomies`
11
+ - [Audit log](/reference/generators/audit-log) — `bin/rails g trek:audit_log`
12
+ - [Public accounts](/reference/generators/public-accounts) — `bin/rails g trek:public_accounts`
13
+ - [Security headers](/reference/generators/security-headers) — `bin/rails g trek:install:security_headers`
14
+ - [Deploying to Scalingo](/deploy) — `bin/rails g trek:scalingo`
15
+ - `bin/rails g trek:upgrade:v2` — upgrades to Trek 2.0: moves the gem and the npm package from the private GitLab sources to RubyGems and npmjs.com
14
16
 
15
17
  ## Models
16
18
 
@@ -19,7 +21,7 @@ Generated into your application — they're yours to read and modify.
19
21
  - [Page](/reference/models/page), [PageVersion](/reference/models/page-version), [PagePath](/reference/models/page-path)
20
22
  - [Fragment](/reference/models/fragment)
21
23
  - [MenuNode](/reference/models/menu-node), [ExternalLink](/reference/models/external-link)
22
- - [User](/reference/models/user) (and its session & password-reset form models)
24
+ - [User](/reference/models/user) (and its deprecated session form model)
23
25
  - [Tag, TagCategory & Tagging](/reference/models/tag) (with the taxonomies generator)
24
26
  - [Current](/reference/models/current)
25
27
 
@@ -2,10 +2,12 @@
2
2
 
3
3
  Request-scoped global context, built on `ActiveSupport::CurrentAttributes` and generated into `app/models/current.rb`.
4
4
 
5
- Trek uses it to cache per-request data — for instance the loaded icon set:
5
+ Trek uses it for per-request data:
6
6
 
7
7
  ```ruby
8
- Current.icons
8
+ Current.session # the signed-in admin's User::Session, set by Trek::Authentication
9
+ Current.user # its user (nil when signed out)
10
+ Current.icons # the icons rendered on the page, for the icon sprite
9
11
  ```
10
12
 
11
- Extend it with your own request-scoped attributes as your application grows (current user, tenant, locale…).
13
+ [`trek:public_accounts`](/reference/generators/public-accounts) adds its account's attributes, e.g. `Current.customer`. Extend it with your own request-scoped attributes as your application grows (tenant, locale…).
@@ -16,7 +16,7 @@ Version history for [pages](/reference/models/page): every snapshot of a version
16
16
 
17
17
  - `belongs_to :page` — with `Page#versions` ordered most recent first
18
18
  - Validations guarantee **one and only one** current version per page
19
- - `after_initialize` sets a default name like `"Page title (2026-06-10)"`
19
+ - `after_initialize` sets a default name like `"Page title (2026-06-10)"`, the date in the current locale's format (`10/06/2026` in French)
20
20
  - Includes [Sectionable](/reference/concerns/sectionable), `RecordImageUploader::Attachment(:image)` and `strip_attributes`
21
21
 
22
22
  ## Notable methods
@@ -13,7 +13,7 @@ It is the admin's account. The site's or the mobile app's users (customers, memb
13
13
  | `theme` | integer | enum, default `auto` |
14
14
  | `locale` | string | admin UI language |
15
15
  | `password_digest` | string | `has_secure_password` (bcrypt), required |
16
- | `last_activity_at` | datetime | updated after each signed-in admin request |
16
+ | `last_activity_at` | datetime | updated while signed in, at most every 5 minutes (see [Sessions](#sessions)) |
17
17
  | `password_changed_at` | datetime | when the password was last set, for its expiry |
18
18
  | `password_renewal_required_at` | datetime | when an admin asked everyone for a new password (`password_renewal_required?`) |
19
19
  | `failed_sign_in_count` | integer | failed sign-ins in a row, for the [lockout](#failed-sign-ins) |
@@ -61,7 +61,7 @@ Each signed-in browser is a `User::Session`, which `Trek::Users::SessionLifetime
61
61
  | `lifetime` | 30 days | since signing in, whatever the activity; also the cookie's expiry |
62
62
  | `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 |
63
63
 
64
- 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"`).
64
+ 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: the installer schedules it every night in GoodJob's cron (see [Scheduled jobs](/background-jobs#scheduled-jobs-cron)); with another Active Job backend, schedule it daily.
65
65
 
66
66
  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.
67
67
 
@@ -70,7 +70,7 @@ Users see their **active sessions** in a tab of their own profile: browser and s
70
70
  `Trek::Users::SignIns` helps users spot a sign-in that wasn't theirs:
71
71
 
72
72
  - 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;
73
- - a sign-in from a **browser that never signed in as the user** emails them (`AdminMailer#new_sign_in`): date, browser, IP address and its host name (as on the active sessions), 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.
73
+ - a sign-in from a **browser that never signed in as the user** emails them (`AdminMailer#new_sign_in`): date, browser, IP address and its host name (as on the active sessions), with links to change their password and to their active sessions. A browser is recognized by an encrypted cookie listing the last 20 users who signed in from it, kept 13 months after the last of those sign-ins: a browser that didn't sign in for longer counts as new again. Their very first sign-in sends nothing.
74
74
 
75
75
  Set `self.new_sign_in_email = false` in the `User` model to turn the email off.
76
76
 
@@ -128,7 +128,7 @@ User.create(email: "new@example.com", role: :editor, send_invite: true)
128
128
  `Trek::Users::Validations` enforces:
129
129
 
130
130
  - `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)
131
- - `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))
131
+ - `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. `Trek::Users::PasswordHistory` also refuses one of the user's last 5 passwords (see [Previous passwords](#previous-passwords))
132
132
 
133
133
  ### Disposable email addresses
134
134
 
@@ -183,7 +183,4 @@ end
183
183
 
184
184
  ## Form models
185
185
 
186
- Two non-persisted `ActiveModel::Model` companions handle the auth flows:
187
-
188
- - **`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
189
- - **`Trek::UserPasswordReset`** — `email`, looks up the `user` to send a reset link to
186
+ **`Trek::UserSession`**, a non-persisted `ActiveModel::Model`, holds the `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.
@@ -19,6 +19,31 @@ Configured per environment in the generated Shrine initializer (`config/initiali
19
19
 
20
20
  Image processing uses libvips, blurhash placeholders are generated for progressive loading, and direct uploads go through the Shrine `upload_endpoint`: `POST /admin/upload/image` (20 MB max) and `POST /admin/upload/audio` (200 MB max), handled by the generated `Admin::UploadsController`. The endpoint only checks the size; each uploader validates the file type when it is attached to a record.
21
21
 
22
+ ## Images: types and sizes
23
+
24
+ `ImageUploader` accepts JPEG, PNG and WebP images, up to 20 MB and 8000 × 8000 pixels.
25
+
26
+ ### Image metadata
27
+
28
+ A photo carries metadata a published file shouldn't: its EXIF (the GPS location where it was taken, the camera's make, model and serial number, the date), XMP and IPTC. `ImageUploader` strips it as a file is uploaded, before it reaches the `cache` storage, so it's never stored nor published. libvips re-encodes the image in its own format (a JPEG or a WebP at quality 90, every frame of an animated WebP): it applies the EXIF orientation first, so a photo taken sideways stays upright, and keeps the color profile (ICC) with libvips 8.15 or later; an older libvips strips it too, and the image is shown as sRGB.
29
+
30
+ A file promoted from the cache to the store isn't processed again.
31
+
32
+ Images uploaded before Trek stripped this metadata still carry it (their [sizes](#sizes) don't). To strip it, once the app's `ImageUploader` strips it on upload:
33
+
34
+ ```bash
35
+ DRY_RUN=1 bin/rails trek:attachments:strip_image_metadata # only lists them
36
+ bin/rails trek:attachments:strip_image_metadata
37
+ ```
38
+
39
+ The task goes through the files of the `store` storage (S3, the file system, or in memory): the JPEG, PNG and WebP images, and the sizes under `derivatives/`. It re-encodes each one carrying metadata as `ImageUploader` does on upload, and replaces it in place, under the same id and with the same `Content-Type` and `Content-Disposition`: every record, page version and content editor image block pointing to it keeps working, and so do the files no record points to anymore, which are still published. Each line gives the status (`stripped`, `strippable` on a dry run, `failed` when libvips can't read the file) and the file id. The records keep the file's former size in their metadata. Re-encoding can't be undone: enable the bucket's versioning, or copy it, first.
40
+
41
+ ### Sizes
42
+
43
+ Thumbnails and other sizes come from Shrine's [derivation endpoint](https://shrinerb.com/docs/plugins/derivation_endpoint), mounted at `/derivations/image`: `Trek::ThumbnailHelper.thumbnail_url(file, width, height)`, or `file.derivation_url(:thumbnail, width, height)`, gives the URL of the image resized to fit within `width` × `height`. A size is made on its first request, then stored under `derivatives/` and served from there. The sizes of an image are deleted with it, when Shrine deletes it: its record destroyed, or the image replaced or removed. Every size is a WebP at quality 80, without metadata, whatever the original's type.
44
+
45
+ The URLs are signed with the `shrine.derivation_endpoint.secret_key` of the credentials, which `trek:install:attachments` writes, or a key derived from `secret_key_base` without it.
46
+
22
47
  ## Attachments and records reloaded mid-save
23
48
 
24
49
  `RecordImageUploader` loads `Trek::SavedAttachmentsReload` on top of Shrine's `activerecord` plugin:
@@ -34,7 +34,7 @@ The domains come from the [valid_email2](https://github.com/micke/valid_email2)
34
34
  - legit-provider.example
35
35
  ```
36
36
 
37
- 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.
37
+ The list (about 180,000 domains) is loaded on the first check, as valid_email2's sorted list: a single string of about 3 MB searched by bisection, rather than its default Set of about 35 MB, for about 5 µs per address. An app that sets `ValidEmail2.disposable_domains_lookup = :sorted_list`, so that valid_email2's own checks (`disposable: true`…) use that list too, keeps a single copy of it.
38
38
 
39
39
  ## Email format
40
40
 
data/docs/security.md CHANGED
@@ -13,15 +13,15 @@ The controls of ISO/IEC 27001:2022's Annex A that an application takes part in:
13
13
  | **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) |
14
14
  | **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) |
15
15
  | **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) |
16
- | **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) |
16
+ | **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. Uploaded images lose their metadata (GPS location, camera serial number). The personal data Trek's generators create is listed, with how long it's kept and what deletes it | [Personal data](/personal-data), [Audit log › Personal data](/reference/generators/audit-log#personal-data) |
17
17
  | **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) |
18
- | **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) |
19
- | **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) |
18
+ | **8.8** Management of technical vulnerabilities | Generated apps' CI runs Brakeman and checks their gems (bundler-audit) and the npm packages they bundle (`yarn npm audit`) for known vulnerabilities, 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), [Vulnerable dependencies](/reference/generators/install#vulnerable-dependencies), [Software Bill of Materials](/reference/generators/install#software-bill-of-materials) |
19
+ | **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. `bin/rails trek:security:check` checks a deployed app still follows the recommended settings | [Installer](/reference/generators/install), [Security headers](/reference/generators/security-headers), [Self-check](#self-check) |
20
20
  | **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) |
21
21
  | **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) |
22
22
  | **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) |
23
23
  | **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) |
24
- | **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) |
24
+ | **8.25** to **8.29** Secure development | Trek's changes go through merge requests, with specs, RuboCop, Brakeman, bundler-audit and `yarn npm audit` in CI. Generated apps get the same CI, and specs checking Trek's behaviour in them | [Installer](/reference/generators/install) |
25
25
  | **8.33** Test information | Planned: anonymized production dumps for development | |
26
26
 
27
27
  ## NIS2 measures
@@ -33,9 +33,9 @@ The measures of the directive's Article 21(2), and what Trek provides for each:
33
33
  | (a) Risk analysis and security policies | — |
34
34
  | (b) Incident handling | Evidence: the audit log, AppSignal's errors, the sign-in emails |
35
35
  | (c) Business continuity, backups, disaster recovery | — |
36
- | (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 |
37
- | (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 |
38
- | (f) Assessing the measures' effectiveness | — |
36
+ | (d) Supply chain security | Dependencies checked for known vulnerabilities in CI: gems (bundler-audit) and the npm packages an app bundles (`yarn npm audit`, which also fails on deprecated packages), with [how to resolve one](/reference/generators/install#vulnerable-dependencies); 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. The [third parties](/personal-data#third-parties) a default app sends personal data to, and what |
37
+ | (e) Secure development and maintenance, vulnerability handling and disclosure | Changes through merge requests, with specs, RuboCop, Brakeman, bundler-audit and `yarn npm audit` in CI; generated apps get the same CI. Planned: a vulnerability disclosure policy |
38
+ | (f) Assessing the measures' effectiveness | `bin/rails trek:security:check` checks a deployed app's configuration against the recommended settings, and prints a dated report to keep as evidence (see [Self-check](#self-check)) |
39
39
  | (g) Cyber hygiene and training | — |
40
40
  | (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 |
41
41
  | (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 |
@@ -52,8 +52,8 @@ The cryptography a generated app uses, with Rails 8.1's defaults: an inventory f
52
52
  | Use | Algorithm | Against a quantum computer |
53
53
  | --- | --- | --- |
54
54
  | Passwords | bcrypt, cost 12 | Resists |
55
- | Rails' session cookie (flash messages, CSRF token) | AES-256-GCM | Resists |
56
- | Signed cookies: the session id, the browsers a user signed in from | HMAC-SHA1 | Resists |
55
+ | Rails' session cookie (flash messages, CSRF token), the browsers a user signed in from | AES-256-GCM | Resists |
56
+ | Signed cookies: the session id | HMAC-SHA1 | Resists |
57
57
  | Password reset and invitation links (`generates_token_for`) | HMAC-SHA1 | Resists |
58
58
  | Keys of the above, derived from `secret_key_base` | PBKDF2-HMAC-SHA256, 1,000 iterations | Resists |
59
59
  | 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 |
@@ -88,3 +88,24 @@ For an app whose client is subject to ISO 27001 or NIS2:
88
88
  - 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));
89
89
  - list the CDN's ranges in `trusted_proxies` when there is one ([Proxies](/proxies));
90
90
  - when the admins work from known networks (an office, a VPN), restrict the admin to them with `ADMIN_ALLOWED_IPS`.
91
+
92
+ ## Self-check
93
+
94
+ `bin/rails trek:security:check` checks a deployed app against the settings above, and what Trek expects from the hosting. Run it where the app runs in production, so it reads that configuration and database, e.g. from a shell on the server or through the hosting platform's command runner. It prints each check with a link to the page explaining it:
95
+
96
+ - **✓** the setting follows the recommendation;
97
+ - **•** a fact, for information: the number of admin users, whether `trusted_proxies` is set, `ADMIN_ALLOWED_IPS` left unset;
98
+ - **⚠** a recommendation not followed, e.g. admins signing in with a password only, a Content Security Policy that only reports, or the purge of expired sessions not scheduled;
99
+ - **✗** a setting Trek relies on: HTTPS, a Content Security Policy, a cache store shared by the app's processes, GoodJob's cron, the audit log's purge.
100
+
101
+ It checks HTTPS and HSTS, the Content Security Policy, the cache store, the proxies and `ADMIN_ALLOWED_IPS`, the audit log and the scheduled purges, the admin users (those signing in with a password only, those who haven't signed in for 6 months, password expiry), and Active Record Encryption's keys. The report starts with the date, the app, and Trek's, Rails' and Ruby's versions: keep it as evidence that the measures are in place.
102
+
103
+ The task exits with status 1 when a check fails, so a scheduled job or a deploy step can stop on it. Run it before going live, after changing the hosting or the app's configuration, and at least once a year.
104
+
105
+ ### In the admin
106
+
107
+ The admin's **Settings › Security** page shows the same checks to admins (editors are turned away), dated, to print or save as evidence without access to a production shell. It also checks the request that opened it, which the task can't: that it reached the app over HTTPS, and the IP address Rails sees. A CDN that forwards another address in its own header (`CF-Connecting-IP`, `True-Client-IP`, `Fastly-Client-IP`) than the one Rails sees fails the check, as its ranges are missing from `trusted_proxies`. The page comes from `bin/rails g trek:install:admin:security_check`, which `trek:install` runs.
108
+
109
+ ### Outside the app
110
+
111
+ The task reads the configuration only. Check what reaches the browser with external tools too: [Mozilla Observatory](https://developer.mozilla.org/en-US/observatory) for the security headers, [SSL Labs](https://www.ssllabs.com/ssltest/) for HTTPS, and the IP address Rails sees, as [Proxies](/proxies#checking) explains.
data/docs/what-is-trek.md CHANGED
@@ -11,7 +11,7 @@ Trek ships as a Rails engine (a gem plus an NPM package) that integrates into yo
11
11
  - **Fragments** — reusable chunks of content (a footer text, a hero tagline…) editable from the admin and usable anywhere in your views.
12
12
  - **A content editor** — based on [Tiptap](https://tiptap.dev), with image uploads (Uppy), link insertion and content stored as structured ProseMirror JSON and rendered safely to HTML (see [Content editor](/content-editor)).
13
13
  - **Authentication & authorization** — sign in built on Rails' [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html) with database-backed sessions, password resets, invitations, and [ActionPolicy](https://actionpolicy.evilmartians.io) policies with `admin`, `editor`, `user`, `reader` and `guest` roles.
14
- - **Internationalization** — content translations with [Mobility](https://github.com/shioyama/mobility), locale management with [i18n-tasks](https://github.com/glebm/i18n-tasks), and optional automatic translation through DeepL.
14
+ - **Internationalization** — content translations with [Mobility](https://github.com/shioyama/mobility) and locale management with [i18n-tasks](https://github.com/glebm/i18n-tasks).
15
15
  - **File uploads** — [Shrine](https://shrinerb.com)-backed attachments with S3 or local storage, image processing via libvips, and blurhash placeholders.
16
16
  - **Generators** — an installer that sets up everything above, and a scaffold generator that creates a full admin panel for any model in one command.
17
17
 
@@ -19,7 +19,7 @@ Trek ships as a Rails engine (a gem plus an NPM package) that integrates into yo
19
19
 
20
20
  Trek follows the Rails way:
21
21
 
22
- - **Convention over configuration.** The installer makes opinionated choices (PostgreSQL, Slim, esbuild, PostCSS, RSpec, Standard…) so you don't have to. Every choice can be revisited afterwards — the generated code lives in your application.
22
+ - **Convention over configuration.** The installer makes opinionated choices (PostgreSQL, Slim, esbuild, PostCSS, RSpec, RuboCop with the Rails omakase rules…) so you don't have to. Every choice can be revisited afterwards — the generated code lives in your application.
23
23
  - **Code generation over runtime magic.** Models like `User`, `Page` or `Fragment` are generated into your app with their concerns included, rather than hidden inside the engine. You can read them, edit them, and remove what you don't need.
24
24
  - **Progressive customization.** Start with the defaults, then override views, components, policies or styles as your project grows.
25
25
 
@@ -28,7 +28,7 @@ Trek follows the Rails way:
28
28
  | Dependency | Version |
29
29
  | --- | --- |
30
30
  | Ruby | 3.3+ |
31
- | Rails | 8.0+ |
31
+ | Rails | 8.0 or 8.1 (before 8.1.4, with `gem "json", "< 3"`) |
32
32
  | PostgreSQL | 12+ |
33
33
  | Node | 22+ |
34
34
  | Yarn | 4.x |
@@ -2,6 +2,6 @@ Description:
2
2
  Generates the necessary files to get you up and running with Trek
3
3
 
4
4
  Examples:
5
- rails generate trek:install
5
+ bin/rails generate trek:install
6
6
 
7
7
  This will install Trek and its dependencies.
@@ -45,6 +45,14 @@ module Trek
45
45
  route "resources :audit_logs, only: %i[index show]", namespace: :admin
46
46
  end
47
47
 
48
+ # Rows past the retention window are deleted every night, after the sessions' purge
49
+ def schedule_purge
50
+ schedule_in_good_job_cron :purge_audit_logs,
51
+ job_class: "Trek::AuditLog::PurgeJob",
52
+ cron: "0 4 * * *",
53
+ description: "Delete the audit log rows past the retention window"
54
+ end
55
+
48
56
  def copy_specs
49
57
  template "spec/models/audit_log_spec.rb", "spec/models/audit_log_spec.rb"
50
58
  template "spec/requests/admin/audit_logs_spec.rb", "spec/requests/admin/audit_logs_spec.rb"
@@ -68,6 +68,23 @@ module Trek
68
68
  run "#{command} #{paths}", abort_on_failure: true, verbose: false
69
69
  end
70
70
 
71
+ GOOD_JOB_INITIALIZER = "config/initializers/good_job.rb"
72
+ GOOD_JOB_CRON = /^ *config\.good_job\.cron = \{\n/
73
+
74
+ # Adds a job to the cron of the initializer trek:install:good_job writes, at the top: the hash's
75
+ # last entry keeps its lack of trailing comma. Once: re-running a generator leaves it. Without
76
+ # that initializer, the app runs another backend, and is told what to schedule.
77
+ def schedule_in_good_job_cron(name, job_class:, cron:, description:, args: nil)
78
+ path = File.join(destination_root, GOOD_JOB_INITIALIZER)
79
+ content = File.exist?(path) ? File.read(path) : ""
80
+ return say_status(:schedule, "#{job_class} daily", :yellow) unless content.match?(GOOD_JOB_CRON)
81
+ return if behavior == :invoke && content.match?(/^ *#{name}: \{$/)
82
+
83
+ entry = { cron:, class: job_class, args:, description: }.compact
84
+ lines = entry.map { |key, value| " #{key}: #{value.inspect}" }
85
+ inject_into_file GOOD_JOB_INITIALIZER, " #{name}: {\n#{lines.join(",\n")}\n },\n", after: GOOD_JOB_CRON
86
+ end
87
+
71
88
  def install_npm_dependencies(dependencies, dev: false)
72
89
  run "yarn add #{dependencies.map { |name, version| "#{name}@#{version}" }.join(" ")} #{dev ? "--dev" : ""}", abort_on_failure: true
73
90
  end
@@ -27,8 +27,9 @@ module Trek
27
27
  route 'mount Lookbook::Engine, at: "/lookbook" if Rails.env.development?'
28
28
  end
29
29
 
30
+ # The thumbnails and other sizes (ImageUploader's derivations)
30
31
  def derivation_endpoint
31
- route '# mount ImageUploader.derivation_endpoint => "derivations/image"'
32
+ route 'mount ImageUploader.derivation_endpoint => "derivations/image"'
32
33
  end
33
34
 
34
35
  def add_panels_routes