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
data/docs/deploy.md CHANGED
@@ -14,22 +14,25 @@ Compared with the stock buildpacks, deploys typically go from around 3 minutes t
14
14
 
15
15
  ## Set up the app
16
16
 
17
- Generate the Scalingo files (an `Aptfile` and a `Procfile` with the web process and post-deploy migrations):
17
+ Generate the Scalingo files (an `Aptfile` and a `Procfile` with the web process and post-deploy migrations). The generator also comments out the `kamal` gem `rails new` adds, which drops its SSH dependencies from the bundle:
18
18
 
19
19
  ```sh
20
- rails g trek:scalingo
20
+ bin/rails g trek:scalingo
21
21
  ```
22
22
 
23
23
  Then configure the Scalingo app's environment, pinning the buildpack to a release through its archive:
24
24
 
25
25
  ```sh
26
- scalingo --app <app> env-set BUILDPACK_URL=https://github.com/etaminstudio/trek-buildpack/archive/refs/tags/v0.1.0.tar.gz
26
+ scalingo --app <app> env-set BUILDPACK_URL=https://github.com/etaminstudio/trek-buildpack/archive/refs/tags/v0.1.4.tar.gz
27
27
  scalingo --app <app> env-set 'DATABASE_URL=$SCALINGO_POSTGRESQL_URL'
28
- scalingo --app <app> env-set RAILS_MASTER_KEY=$(cat config/master.key)
28
+ scalingo --app <app> env-set RAILS_MASTER_KEY=$(cat config/master.key) > /dev/null
29
29
  ```
30
30
 
31
+ > `env-set` prints every value it sets, so without `> /dev/null` the master key ends up in the terminal's scrollback and
32
+ > in any log or transcript of the session. Do the same for every secret below.
33
+
31
34
  > Pin through the archive, not a `#tag` suffix: Scalingo reads `#ref` on `BUILDPACK_URL` as a **branch**, so
32
- > `…/trek-buildpack#v0.1.0` asks for a branch named `v0.1.0`, which does not exist, and the build fails with
35
+ > `…/trek-buildpack#v0.1.4` asks for a branch named `v0.1.4`, which does not exist, and the build fails with
33
36
  > `fail to download and extract the custom buildpack: Invalid status code: 404 Not Found`. The `.tar.gz` form above is
34
37
  > downloaded as is and stays pinned to the release.
35
38
 
@@ -44,6 +47,66 @@ production:
44
47
 
45
48
  Provision a PostgreSQL addon (`scalingo --app <app> addons-add postgresql <plan>`), push, and the app boots with `RAILS_ENV`, `RAILS_LOG_TO_STDOUT` and `RAILS_SERVE_STATIC_FILES` already set by the buildpack.
46
49
 
50
+ ### One database
51
+
52
+ The addon is a single database, but the production section `rails new` generates also declares a `cache` database for Solid Cache (`config/cache.yml` says `database: cache`, its schema is `db/cache_schema.rb`). The postdeploy `db:migrate` never loads that schema, so the cache table is never created. Keep the cache in the app's database:
53
+
54
+ * drop the `cache` entry from the production section of `config/database.yml`, and the `database: cache` line from `config/cache.yml`
55
+ * create the table with a regular migration (`bin/rails g migration CreateSolidCacheEntries`), copying `create_table "solid_cache_entries"` and its indexes from `db/cache_schema.rb`
56
+ * delete `db/cache_schema.rb`
57
+
58
+ The same goes for any other extra database in that section (`queue`, `cable`).
59
+
60
+ ### Environment variables
61
+
62
+ Besides the three above, the code Trek generates reads:
63
+
64
+ | Variable | Used for |
65
+ | --- | --- |
66
+ | `DEFAULT_HOSTNAME` | The app's host, for URLs built outside a request, including links in emails (`config/initializers/host.rb`) |
67
+ | `MAILER_FROM` | The sender of the app's emails (`ApplicationMailer`) |
68
+ | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | The uploads' bucket (`config/initializers/shrine.rb`). Required in production: the app doesn't boot without them |
69
+ | `S3_BASE_URL` | The public URL of the bucket's files, e.g. `https://<bucket>.<region>.your-objectstorage.com`. Required in production too |
70
+ | `APPSIGNAL_PUSH_API_KEY` | Turns AppSignal on, unless the key is in the credentials (`config/appsignal.rb`) |
71
+ | `APPSIGNAL_APP_ENV` | The AppSignal environment, e.g. `qa`. The gem reads this name, not `APPSIGNAL_ENV` |
72
+ | `RAILS_MAX_THREADS`, `GOOD_JOB_MAX_THREADS` | Puma's threads and the jobs' threads, which also size the database pool (`config/database.yml`) |
73
+
74
+ Jobs run inside the web container (`config.good_job.execution_mode = :async`), so the generated `Procfile` has no worker to scale.
75
+
76
+ `env-set` doesn't restart the app: running containers keep their old values until `scalingo --app <app> restart`.
77
+
78
+ ### Domains
79
+
80
+ Add each domain to the app, then point it at the app with a CNAME:
81
+
82
+ ```sh
83
+ scalingo --app <app> domains-add <domain>
84
+ # DNS: <domain> CNAME <app>.osc-fr1.scalingo.io.
85
+ ```
86
+
87
+ Scalingo issues the Let's Encrypt certificate once the CNAME resolves; until then the domain shows "Pending DNS".
88
+
89
+ ### Continuous deployment
90
+
91
+ Deploy from GitLab CI rather than linking the Scalingo app to the repository: the deploy then only runs once the pipeline's tests, lint and security jobs have passed. The generated `.gitlab-ci.yml` has a `deploy` stage, with commented-out jobs; replace them with one job per Scalingo app:
92
+
93
+ ```yaml
94
+ qa:
95
+ <<: *deploy_definition
96
+ only:
97
+ - main
98
+ environment:
99
+ name: qa
100
+ url: https://<domain>
101
+ script:
102
+ - curl -O https://cli-dl.scalingo.com/install && bash install
103
+ - scalingo login --api-token $SCALINGO_API_TOKEN
104
+ - tar --exclude=tmp --exclude=log --exclude=spec --exclude=.git --transform='s,^,master/,' -cvzf tmp/main.tar.gz .
105
+ - scalingo --app <app> deploy tmp/main.tar.gz $CI_COMMIT_SHORT_SHA
106
+ ```
107
+
108
+ `SCALINGO_API_TOKEN` is a Scalingo API token, set as a masked CI/CD variable of the project or its group. A `production` job on the `production` branch follows the same pattern.
109
+
47
110
  Before going live, check what Trek expects from the hosting: backups, a shared cache store, the scheduled purges (see [Security and compliance](/security#what-trek-expects-from-the-hosting)).
48
111
 
49
112
  ## Options
@@ -57,7 +120,7 @@ Before going live, check what Trek expects from the hosting: backups, a shared c
57
120
 
58
121
  Apps deployed with the stock `.buildpacks` (apt + ruby) migrate in three steps:
59
122
 
60
- 1. delete `.buildpacks` (re-running `rails g trek:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
123
+ 1. delete `.buildpacks` (re-running `bin/rails g trek:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
61
124
  2. set `BUILDPACK_URL` as above, and map `DATABASE_URL` if the app doesn't read it yet
62
125
  3. deploy — the first build fills the caches, the next ones benefit from them
63
126
 
@@ -7,7 +7,7 @@ This guide takes you from an empty directory to a working Rails application with
7
7
  Make sure the following are installed:
8
8
 
9
9
  - Ruby 3.3+
10
- - Rails 8.0+
10
+ - Rails 8.0 or 8.1: 8.1.4 or later, or add `gem "json", "< 3"` to the Gemfile, as json 3 needs Rails 8.1.4
11
11
  - PostgreSQL 12+
12
12
  - Node 22+
13
13
  - Yarn 4.x
@@ -27,13 +27,20 @@ Check your Yarn version:
27
27
  yarn -v
28
28
  ```
29
29
 
30
- If it's not a 4.x version, run:
30
+ If it's not a 4.x version, or `yarn` isn't found, install it with [corepack](https://github.com/nodejs/corepack). Node 25 and later no longer ship corepack, so install it first:
31
31
 
32
32
  ```sh
33
+ npm install --global corepack
33
34
  corepack enable
34
35
  corepack install --global yarn@4
35
36
  ```
36
37
 
38
+ Or, if you manage your tools with [mise](https://mise.jdx.dev):
39
+
40
+ ```sh
41
+ mise use --global yarn@4
42
+ ```
43
+
37
44
  ## Create your Rails project
38
45
 
39
46
  Replace `helloworld` with your own project name:
@@ -57,7 +64,7 @@ bundle add trek
57
64
  ## Run the installer
58
65
 
59
66
  ```sh
60
- rails g trek:install
67
+ bin/rails g trek:install
61
68
  ```
62
69
 
63
70
  The installer will:
@@ -84,22 +91,12 @@ You can also do it manually afterwards:
84
91
  EDITOR="code --wait" bin/rails credentials:edit
85
92
  ```
86
93
 
87
- ### Configure DeepL (optional)
88
-
89
- DeepL is used to translate locale files automatically when running the scaffold generator. To enable it, define this ENV variable before running the installer:
90
-
91
- ```sh
92
- export DEEPL_AUTH_KEY=YOUR_TOKEN
93
- ```
94
-
95
- Without it, translations won't happen automatically and you will have to edit each non-English locale file by hand.
96
-
97
94
  ## Create an admin user
98
95
 
99
96
  Set `ADMIN_EMAIL` and `ADMIN_PASSWORD` in your `.env`, then run:
100
97
 
101
98
  ```sh
102
- rails g trek:admin:user
99
+ bin/rails g trek:admin:user
103
100
  ```
104
101
 
105
102
  ## Start the server
@@ -115,17 +112,18 @@ Open `http://localhost:3000/admin` and sign in with your admin credentials. Welc
115
112
  Trek's scaffold generator creates everything an admin panel needs for a model:
116
113
 
117
114
  ```sh
118
- rails g trek:scaffold Book title:string intro:text
115
+ bin/rails g trek:scaffold Book title:string intro:text
116
+ bin/rails db:migrate
119
117
  ```
120
118
 
121
119
  This generates, in a single command:
122
120
 
123
- - the `Book` model and migration (calling the Rails `model` generator behind the scenes)
121
+ - the `Book` model and migration (calling the Rails `model` generator behind the scenes), whose `to_s`, the title the admin shows a book by, returns its `title`
124
122
  - the `Admin::BooksController` based on `Trek::ResourceController`
125
123
  - the index, show, new, edit views and form partial
126
124
  - the `Admin::BookPolicy` with role-based permissions
127
125
  - the admin routes
128
- - the locale files (auto-translated via DeepL if configured)
126
+ - the locale files
129
127
  - a menu entry in the admin dashboard
130
128
 
131
129
  Next steps:
data/docs/index.md CHANGED
@@ -29,7 +29,7 @@ features:
29
29
  details: One command generates the model, admin panel, views, policy, routes and locales for any resource — just like Rails scaffolding, but for your back-office.
30
30
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M22 22H5A17 17 0 0 1 22 5ZM22 26V43A17 17 0 0 1 5 26ZM26 26H43A17 17 0 0 1 26 43Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M26 22V5A17 17 0 0 1 43 22Z"/></svg>'
31
31
  title: Multilingual by default
32
- details: Content and admin UI translations powered by Mobility and i18n-tasks, with optional automatic translation via DeepL.
32
+ details: Content and admin UI translations powered by Mobility and i18n-tasks.
33
33
  - icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="32" height="32" aria-hidden="true"><path fill-rule="evenodd" fill="var(--trek-icon-ink, currentColor)" d="M14 22V16A10 10 0 0 1 34 16V22H28V16A4 4 0 0 0 20 16V22ZM8 22H24V42H16A8 8 0 0 1 8 34Z"/><path fill="var(--trek-icon-accent, #63E0A6)" d="M24 22H40V34A8 8 0 0 1 32 42H24Z"/></svg>'
34
34
  title: Roles & policies built in
35
35
  details: Authentication on Rails' own has_secure_password and ActionPolicy authorization with admin, editor, user, reader and guest roles, enforced across every panel.
@@ -0,0 +1,61 @@
1
+ # Personal data
2
+
3
+ The personal data an app gets from Trek's generators: where it's kept, why, for how long, what deletes it, and which third parties receive some of it. It's what a GDPR record of processing activities (Art. 30) and security questionnaires ask for. The app adds its own models to it, and the organization running it decides the legal bases and informs the people concerned.
4
+
5
+ ## In the database
6
+
7
+ | Table | Personal data | Why | Kept | Deleted by |
8
+ | --- | --- | --- | --- | --- |
9
+ | `users` | Name, email, role, language and theme; password hash; last activity; the current and previous sign-ins (date, IP address, user agent); failed sign-ins and lockout; password changes | Signing in to the admin, and showing users their sign-ins to spot one that wasn't theirs | While the account exists | Deleting the user |
10
+ | `user_sessions` | IP address and its host name, user agent, last activity | One row per signed-in browser, listed to its user, who can end it | Until signing out, or 48 hours idle, 30 days in all | Signing out; [`Trek::PurgeExpiredSessionsJob`](/background-jobs#scheduled-jobs-cron), every night; deleting the user |
11
+ | `user_passkeys` | The browser it was added from, its provider, last use | Signing in with a passkey | While the passkey exists | Its user removing it; deleting the user |
12
+ | `user_previous_passwords` | Hashes of the 4 previous passwords | Refusing a password used recently | Until replaced by newer ones | Changing the password (only the last ones stay); deleting the user |
13
+ | `audit_logs` | The author (type and id), IP address, user agent, path, the parameters' names | Investigating an incident or a misuse (see [Audit log › Personal data](/reference/generators/audit-log#personal-data)) | 6 months | [`Trek::AuditLog::PurgeJob`](/reference/generators/audit-log#purging-old-rows), every night |
14
+
15
+ With [public accounts](/reference/generators/public-accounts) (`trek:public_accounts Member`):
16
+
17
+ | Table | Personal data | Why | Kept | Deleted by |
18
+ | --- | --- | --- | --- | --- |
19
+ | `members` | Email, name, last activity; with passwords, the password hash, an email waiting for confirmation, failed sign-ins and lockout | The account | While the account exists | Its holder deleting it; the app (see [below](#retention-to-decide)) |
20
+ | `member_sessions` | IP address and its host name, user agent, last activity | One row per signed-in browser or device | Until signing out, or 30 days idle, 1 year in all | Signing out; `Trek::PurgeExpiredSessionsJob`, every night; deleting the account |
21
+ | `member_sign_in_codes` | The email a code was sent to | Signing in with a code | 10 minutes of validity | The next code requested for that email, which also deletes every expired one; `Trek::PurgeExpiredSignInCodesJob`, every night; deleting the account |
22
+
23
+ ## In the browser
24
+
25
+ - `session_id` (and `member_session_id` with public accounts): a signed cookie naming the session, until signing out or the session's expiry.
26
+ - `trek_known_users`: an encrypted cookie holding the ids of the last 20 users who signed in from this browser, for 13 months after the last of those sign-ins, to email a user when they sign in from a new browser. It serves to secure signing in.
27
+
28
+ ## Uploads
29
+
30
+ Files are stored in the S3-compatible bucket, with metadata in the record's column: the original file name, size, MIME type, and for an image its dimensions and [blurhash](https://blurha.sh). An image's own metadata (EXIF, with the GPS location and the camera's serial number, XMP, IPTC) is stripped on upload, as the file is public: see [Uploaders](/reference/uploaders#image-metadata). Images uploaded before Trek stripped it still carry it, until `bin/rails trek:attachments:strip_image_metadata` strips them in place; their [sizes](/reference/uploaders#sizes) don't.
31
+
32
+ A file is deleted with its record, and with it its sizes (thumbnails…), stored under `derivatives/`; the sizes of images deleted before Trek did that stay in the bucket, at URLs nobody links to any more. A file uploaded to the cache but never attached, e.g. from a form left without saving, stays in the bucket's `cache/` prefix: a lifecycle rule on the bucket deleting `cache/` objects after a day or two takes care of it.
33
+
34
+ ## Deleting a user or an account
35
+
36
+ Deleting a user deletes their sessions, passkeys and previous passwords. Their audit log rows stay, with the id the user had but not their name, until the purge deletes them: they record what was done, which an investigation still needs. Pages, fragments and their versions record no author.
37
+
38
+ Deleting a public account deletes its sessions and sign-in codes; its audit log rows stay until the purge, as for a user.
39
+
40
+ ## Third parties
41
+
42
+ What a default app sends, and to whom:
43
+
44
+ | Service | Receives | When |
45
+ | --- | --- | --- |
46
+ | The hosting | Everything: the database, the logs (which hold the requests' IP addresses) | Always |
47
+ | S3-compatible storage | The uploaded files | Always |
48
+ | [Postmark](https://postmarkapp.com) | The emails sent: their address and content, e.g. password reset links, sign-in codes, and the new sign-in alert, which gives the date, the browser and the IP address | When an email is sent |
49
+ | [AppSignal](https://www.appsignal.com) | Errors and performance: the request's path and parameters as filtered by `filter_parameters` (passwords, emails, tokens…), and the signed-in user's id; CSP violation reports (a page's path, a blocked origin, the file and line that caused it, the start of a blocked inline script, the browser's user agent) | On every request it samples, and on every error |
50
+ | The DNS resolver | A session's IP address, for its host name (reverse lookup) | After each sign-in |
51
+ | [Have I Been Pwned](https://haveibeenpwned.com/API/v3#PwnedPasswords) | The first 5 characters of the new password's SHA-1 hash, never the password | When a password is set, if `password_check_pwned` is on (off by default) |
52
+
53
+ The admin's fonts are served by the app itself: its pages make no request to a font provider.
54
+
55
+ ## Retention to decide
56
+
57
+ What Trek leaves to each app:
58
+
59
+ - **Inactive accounts.** Users and public accounts are kept until deleted. `Member.inactive_since(time)` lists the accounts unused since `time`, to delete them on the schedule the organization sets.
60
+ - **The uploads' cache**, as [above](#uploads).
61
+ - **The logs**, kept by the hosting: set their retention there.
data/docs/proxies.md CHANGED
@@ -4,7 +4,7 @@ Trek relies on `request.remote_ip`, the visitor's IP address as Rails works it o
4
4
 
5
5
  - the **active sessions** list, on each user's profile;
6
6
  - the **audit log** (`ip_address`), when installed;
7
- - the **rate limits** on signing in and on password reset requests (5 attempts in 3 minutes per address);
7
+ - the **rate limits** on signing in and on password reset requests (5 attempts in 3 minutes per address), and on the admin's failed sign-ins (20 an hour per address);
8
8
  - the **admin's allowed addresses**, when set (see [below](#restricting-the-admin-to-ip-addresses)).
9
9
 
10
10
  ## How Rails finds the address
@@ -16,7 +16,7 @@ Requests rarely reach the app directly: a hosting platform's load balancer or ro
16
16
  A CDN or a firewall in front of the app (Cloudflare, Imperva, Bunny…) adds another hop, from public addresses Rails doesn't trust. `remote_ip` is then the CDN's address for every request:
17
17
 
18
18
  - every session and every audit log row shows the same IP;
19
- - everyone shares one rate limit: a few failed sign-ins anywhere lock everyone out for 3 minutes.
19
+ - everyone shares the rate limits: a few failed sign-ins anywhere lock everyone out for 3 minutes, and 20 for up to an hour.
20
20
 
21
21
  List the CDN's address ranges, which it publishes, in `config/application.rb`:
22
22
 
@@ -18,10 +18,10 @@ The main building blocks, all in the `Trek::` namespace:
18
18
  | `ListComponent` | record lists |
19
19
  | `PropertiesComponent` | key-value property display |
20
20
  | `PaginationComponent` | Kaminari-backed pagination |
21
- | `ToasterComponent` / `ToastComponent` | flash notifications |
21
+ | `ToasterComponent` / `Toaster::ToastComponent` | flash notifications |
22
22
  | `HeadingComponent` | headings |
23
23
  | `SectionComponent` | a titled section of a page, with an optional hint under its heading |
24
- | `GateComponent` | authorization-based visibility gate |
24
+ | `GateComponent` | the frame of the sign-in and password reset screens: a centred card under the brand |
25
25
  | `IconComponent` | SVG [icon](/reference/icons) renderer |
26
26
  | `Dashboard::SectionComponent` / `Dashboard::TileComponent` | dashboard sections of shortcut tiles |
27
27
 
@@ -1,17 +1,23 @@
1
1
  # Trek::Fragmentable
2
2
 
3
- Composes a record from reusable [fragments](/reference/models/fragment), based on a configuration matrix mapping record keys to fragment ids.
3
+ Composes a record from reusable [fragments](/reference/models/fragment), based on a configuration matrix mapping record keys to the attributes finding each fragment.
4
4
 
5
5
  ## Configuration
6
6
 
7
+ In `config/page_fragments.yml`, read with `config_for`, so under `shared:` or an environment's key:
8
+
7
9
  ```yaml
8
- # page_fragments configuration
9
- page_fragments:
10
+ shared:
10
11
  matrix:
11
- home: [1, 2, 3]
12
- about: [4, 5]
12
+ home:
13
+ - { namespace: home, key: intro }
14
+ - { namespace: home, key: newsletter }
15
+ about:
16
+ - { namespace: about, key: team }
13
17
  ```
14
18
 
19
+ Each entry is passed to `Fragment.find_by`. Without the file, a record has no fragments.
20
+
15
21
  ## Methods
16
22
 
17
23
  | Method | Purpose |
@@ -27,7 +33,7 @@ class Page < ApplicationRecord
27
33
  end
28
34
 
29
35
  page = Page.find_by(key: "home")
30
- page.fragments # => [Fragment(1), Fragment(2), Fragment(3)]
36
+ page.fragments # => the home/intro and home/newsletter fragments
31
37
  ```
32
38
 
33
39
  This is what powers the fragment editing UI on page forms in the admin.
@@ -5,7 +5,7 @@ Position tracking with [acts_as_list](https://github.com/brendon/acts_as_list),
5
5
  ## What it adds
6
6
 
7
7
  - `acts_as_list scope: :parent, top_of_list: 0`
8
- - An `ordered` scope (position order)
8
+ - An `ordered` scope (position order), which adds nothing on a [closure_tree](https://github.com/ClosureTree/closure_tree) model such as `Page` or `MenuNode`: closure_tree already orders its records by `position`
9
9
  - All the `acts_as_list` instance methods: `insert_at`, `move_to_top`, `move_to_bottom`, `move_higher`, `move_lower`…
10
10
 
11
11
  ## Requirements
@@ -19,7 +19,7 @@ class MenuNode < ApplicationRecord
19
19
  include Trek::Orderable
20
20
  end
21
21
 
22
- MenuNode.where(parent: menu).ordered
22
+ menu.children # ordered by position, through closure_tree
23
23
  node.move_to_top
24
24
  ```
25
25
 
@@ -1,6 +1,6 @@
1
1
  # Trek::Pages::SearchEngineOptimizable
2
2
 
3
- SEO metadata with sensible fallbacks: explicit title/description/image when set, model defaults otherwise (including the parent page's image).
3
+ SEO metadata from the page's title, description and image: a blank title or description gives `""`, a missing image `nil`. Override the `default_*` methods to fall back on other values.
4
4
 
5
5
  ## Methods
6
6
 
@@ -19,4 +19,17 @@ Article.search("élève") # matches "eleve", "Élève"…
19
19
 
20
20
  ## Controller side
21
21
 
22
- The `Trek::Search` controller concern wires this into index actions: it filters `@objects` by `params[:search]` whenever the model responds to `search` — that's what powers the search field in admin lists.
22
+ The `Trek::Search` concern wires this into an admin controller's index, as the generated fragments controller does. It's opt-in: include it and call `search_in_objects!` after loading `@objects`:
23
+
24
+ ```ruby
25
+ class Admin::ArticlesController < Trek::ResourceController
26
+ include Trek::Search
27
+
28
+ def index
29
+ super
30
+ search_in_objects!
31
+ end
32
+ end
33
+ ```
34
+
35
+ `search_in_objects!` filters `@objects` by `params[:search]` when it's present, and raises `Trek::Search::ModelNotSearchable` when the model has no `search` scope.
@@ -4,16 +4,20 @@ Organizes a record's content into ordered, typed sections (hero, features, testi
4
4
 
5
5
  ## What it adds
6
6
 
7
+ When the app has a `Section` model:
8
+
7
9
  - `has_many :sections, -> { ordered }, as: :sectionable, dependent: :destroy`
8
10
  - `sections_instances` — the unwrapped section objects, in order
9
11
 
12
+ ## Requirements
13
+
14
+ Trek doesn't generate the `Section` model: the app provides it, with a polymorphic `belongs_to :sectionable`, an `ordered` scope, and a `section` method returning the section's own object. Without a `Section` model, the concern adds nothing.
15
+
10
16
  ## Usage
11
17
 
12
18
  ```ruby
13
19
  class Page < ApplicationRecord
14
20
  include Trek::Sectionable
15
-
16
- SECTIONS = [HeroSection, FeaturesSection].freeze
17
21
  end
18
22
 
19
23
  page.sections_instances.each do |section|
@@ -21,4 +25,4 @@ page.sections_instances.each do |section|
21
25
  end
22
26
  ```
23
27
 
24
- Sections are opt-in per page via the `sectioned` boolean column. The including class defines the allowed section types through the `SECTIONS` constant.
28
+ Sections are opt-in per page via the `sectioned` boolean column.
@@ -4,7 +4,7 @@ Content versioning for [pages](/reference/models/page): snapshot the current con
4
4
 
5
5
  ## What it adds
6
6
 
7
- - `has_many :versions` (most recent first) with a `current` sub-scope, plus `accepts_nested_attributes_for :versions`
7
+ - `has_many :versions` (most recent first), plus `accepts_nested_attributes_for :versions`; `page.versions.current` returns the current version, a record (or `nil`)
8
8
 
9
9
  ## Methods
10
10
 
@@ -20,9 +20,41 @@ end
20
20
  ## Mixins
21
21
 
22
22
  - `include Trek::Pagination` — paginates the index with Kaminari
23
- - `include Trek::Search` — filters the index by `params[:search]` when the model is [Searchable](/reference/concerns/searchable)
23
+ - `include Trek::Search` — adds `search_in_objects!`, to call in `index`: it filters the index by `params[:search]`, for a [Searchable](/reference/concerns/searchable) model
24
24
  - `include Trek::Filters` — filters the index by attribute equality (`where(column => value)`) from `params[:filters]`
25
25
  - `include Trek::Scopes` — filters the index by **named scopes** from `params[:scopes]`
26
+ - `include Trek::Localization` — answers each request in the [locale](#localization) of the request, the user or the browser
27
+
28
+ ### Localization
29
+
30
+ `Trek::Localization` sets `I18n.locale` around each action, and restores the previous locale afterwards, even when
31
+ the action raises. `Trek::BaseController` includes it, as do the generated `Admin::BaseController` and
32
+ `Admin::UploadsController`. Include it in an app's own controllers, e.g. public pages, for the same behaviour.
33
+
34
+ The locale is the first one found among:
35
+
36
+ 1. `params[:locale]`, e.g. `?locale=fr`
37
+ 2. the signed-in user's `locale` (`Current.user`, set by `Trek::Authentication`)
38
+ 3. the browser's `Accept-Language` header: its first language among `I18n.available_locales`, a regional
39
+ variant matching its language (`fr-CA` gives `fr`), through [http_accept_language](https://github.com/iain/http_accept_language)
40
+
41
+ Without any, the request is answered in `I18n.default_locale`.
42
+
43
+ To add a source, or a fallback other than the default locale, override `locale_for_request` and call `super` for
44
+ Trek's chain:
45
+
46
+ ```ruby
47
+ class EventsController < ApplicationController
48
+ include Trek::Localization
49
+
50
+ private
51
+
52
+ # The event's own language first, then Trek's chain
53
+ def locale_for_request
54
+ Current.event&.locale.presence || super
55
+ end
56
+ end
57
+ ```
26
58
 
27
59
  ### Filters
28
60
 
@@ -7,8 +7,8 @@
7
7
  | `POSTMARK_API_TOKEN` | Postmark email delivery (auto-injected into credentials by the [installer](/reference/generators/install)) |
8
8
  | `APPSIGNAL_PUSH_API_KEY` | AppSignal error tracking and performance monitoring (auto-injected into credentials by the [installer](/reference/generators/install)) |
9
9
  | `APPSIGNAL_APP_ENV` | environment name reported to AppSignal (optional, defaults to `RAILS_ENV`) |
10
- | `DEEPL_AUTH_KEY` | automatic locale translation in the [scaffold generator](/reference/generators/scaffold) |
11
10
  | `FEATURE_AUDIT_LOG` | `false` stops the [audit log](/reference/generators/audit-log) recording requests (on by default) |
12
11
  | `GOOD_JOB_MAX_THREADS` | number of job threads GoodJob runs, and the share of the database pool reserved for them (optional, defaults to `RAILS_MAX_THREADS`) — see [Background jobs](/background-jobs) |
13
- | `FEATURE_STORAGE` | `local` (development) or `s3` (production) |
12
+ | `FEATURE_STORAGE` | `s3` stores the uploads on S3 outside production too, e.g. in development; otherwise development stores them in `public/uploads` and the tests in memory. Production always uses S3 |
13
+ | `TREK_LOCALES` | the locales the [installer](/reference/generators/install) sets up, comma-separated, e.g. `en,fr,de` (the `--locales` option of `trek:install:locales` too; defaults to `en, fr`) |
14
14
  | `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BASE_URL` | S3 storage configuration for [uploads](/reference/uploaders) |
@@ -4,7 +4,8 @@
4
4
 
5
5
  `Trek::TypographyFormatter` applies French typography rules to strings **and** ProseMirror documents (only `text` nodes are modified):
6
6
 
7
- - non-breaking spaces before `: ; ! ? % € $ »` and after `«`, dashes, `n°`
7
+ - non-breaking spaces before `»`, after `«`, `n°`, and on both sides of dashes (`–`, `—`)
8
+ - before `: % € $`, a non-breaking space, and before `; ! ?` a narrow one (U+202F): only when the sign ends a word (followed by a space, punctuation or the end of the text), so a time (`10:30`) or a URL is left alone
8
9
  - non-breaking spaces before units (km, kg, h, min, °C…) and between digit groups
9
10
  - `...` → `…`, ASCII apostrophes → typographic `'`
10
11
  - removes double spaces and spaces before periods/commas
@@ -4,7 +4,7 @@ Trek ships `Trek::FormBuilder`, an extension of [`ViewComponent::Form`](https://
4
4
 
5
5
  | Helper | Renders |
6
6
  | --- | --- |
7
- | `f.group` | a label + input wrapper with errors |
7
+ | `f.group` | a wrapper giving the input nested in it a label, and a hint (errors are listed by `Trek::Form::ErrorsComponent`) |
8
8
  | `f.content_editor` | the [content editor](/content-editor), based on Tiptap |
9
9
  | `f.image_field` | an image uploader with thumbnail preview (Uppy + Shrine) |
10
10
  | `f.sound_field` | an audio file uploader |
@@ -18,6 +18,9 @@ Standard helpers are styled too: a plain `f.file_field` inside an `f.group` gets
18
18
  ```slim
19
19
  = form_with model: [:admin, @book] do |f|
20
20
  = f.group :title
21
- = f.content_editor :intro, floating: false
22
- = f.switch_box :published
21
+ = f.text_field :title
22
+ = f.group :intro
23
+ = f.content_editor :intro, floating: false
24
+ = f.group :published
25
+ = f.switch_box :published
23
26
  ```
@@ -1,7 +1,7 @@
1
1
  # Admin user
2
2
 
3
3
  ```sh
4
- rails g trek:admin:user
4
+ bin/rails g trek:admin:user
5
5
  # or (soon)
6
6
  trek admin:user
7
7
  ```
@@ -1,7 +1,7 @@
1
1
  # Audit log
2
2
 
3
3
  ```sh
4
- rails g trek:audit_log
4
+ bin/rails g trek:audit_log
5
5
  bin/rails db:migrate
6
6
  ```
7
7
 
@@ -43,6 +43,10 @@ class Api::BaseController < ActionController::API
43
43
  # Record reads as well as mutations
44
44
  self.audit_reads = true
45
45
 
46
+ # Actions that only read although they're not a GET, skipped as reads are (default: none),
47
+ # e.g. the chips hotwire_combobox requests with a POST
48
+ self.audit_read_actions = %i[chips]
49
+
46
50
  # The parameters whose values are recorded, the others by name only (default: id and role)
47
51
  self.audit_param_values = %w[id role status]
48
52
 
@@ -77,19 +81,14 @@ end
77
81
 
78
82
  ## Purging old rows
79
83
 
80
- `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`:
84
+ `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). The generator schedules it every night in GoodJob's cron, in the `config/initializers/good_job.rb` the installer writes. With another Active Job backend, it says so, and the job is to schedule daily with that backend. An app that installed the audit log before the generator did this adds the entry to its `config.good_job.cron` by hand:
81
85
 
82
86
  ```ruby
83
- Rails.application.configure do
84
- config.good_job.enable_cron = true
85
- config.good_job.cron = {
86
- purge_audit_logs: {
87
- cron: "0 4 * * *",
88
- class: "Trek::AuditLog::PurgeJob",
89
- description: "Delete the audit log rows past the retention window"
90
- }
91
- }
92
- end
87
+ purge_audit_logs: {
88
+ cron: "0 4 * * *",
89
+ class: "Trek::AuditLog::PurgeJob",
90
+ description: "Delete the audit log rows past the retention window"
91
+ },
93
92
  ```
94
93
 
95
94
  To keep the rows longer or shorter, set the retention in an initializer: `Trek::AuditLog::PurgeJob.retention = 1.year`.
@@ -108,6 +107,6 @@ The rows hold personal data: the author, the IP address, the user agent, and wha
108
107
 
109
108
  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:
110
109
 
111
- 1. Run `rails g trek:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
110
+ 1. Run `bin/rails g trek:audit_log`, delete the generated `db/migrate/*_trek_audit_logs.rb`, and let the generator overwrite the model, controller, views and policy.
112
111
  2. Delete the app's `Auditable` concern, its initializer and its purge job, and update the job's cron entry to `Trek::AuditLog::PurgeJob`.
113
112
  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.