trek 2.5.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.
- checksums.yaml +4 -4
- data/.node-version +1 -1
- data/AGENTS.md +18 -14
- data/CHANGELOG.md +88 -0
- data/Gemfile +5 -0
- data/Gemfile.lock +135 -124
- data/Makefile +9 -1
- data/README.md +17 -21
- data/app/components/trek/dashboard/tile_component/tile_component.css +9 -0
- data/app/components/trek/dashboard/tile_component/tile_component.html.slim +4 -2
- data/app/components/trek/dashboard/tile_component.rb +12 -2
- data/app/components/trek/form/content_editor_component/content_editor_component.css +9 -8
- data/app/components/trek/form/content_editor_component/content_editor_component.html.slim +19 -93
- data/app/components/trek/form/content_editor_component/content_editor_component.js +94 -251
- data/app/components/trek/form/content_editor_component/extensions/block_view.js +40 -0
- data/app/components/trek/form/content_editor_component/extensions/image_block.js +28 -26
- data/app/components/trek/form/content_editor_component/extensions/prompts_block.js +15 -26
- data/app/components/trek/form/content_editor_component/extensions/table_of_contents.js +1 -3
- data/app/components/trek/form/content_editor_component.rb +15 -0
- data/app/components/trek/form/image_field_component/image_field_component.css +40 -1
- data/app/components/trek/form/image_field_component/image_field_component.html.slim +0 -9
- data/app/components/trek/form/image_field_component/image_field_component.js +1 -2
- data/app/components/trek/form/image_field_component.rb +36 -9
- data/app/components/trek/form/password_strength_component/password_strength_component.css +2 -0
- data/app/components/trek/form/sound_field_component/sound_field_component.js +1 -2
- data/app/components/trek/security_check_component/security_check_component.css +69 -0
- data/app/components/trek/security_check_component/security_check_component.html.slim +19 -0
- data/app/components/trek/security_check_component/security_check_component.js +15 -0
- data/app/components/trek/security_check_component.rb +19 -0
- data/app/content/trek/content/cleaner.rb +53 -0
- data/app/content/trek/content/document.rb +2 -2
- data/app/content/trek/content/list_item.rb +1 -1
- data/app/content/trek/content/paragraph.rb +7 -2
- data/app/content/trek/content/prompts_block.rb +1 -2
- data/app/content/trek/content.rb +6 -0
- data/app/controllers/concerns/trek/auditable.rb +5 -2
- data/app/controllers/concerns/trek/localization.rb +6 -2
- data/app/controllers/concerns/trek/reorderable.rb +24 -6
- data/app/controllers/trek/csp_reports_controller.rb +14 -1
- data/app/controllers/trek/panels/prompts_controller.rb +1 -1
- data/app/controllers/trek/resource_controller.rb +5 -5
- data/app/jobs/trek/purge_expired_sessions_job.rb +4 -3
- data/app/jobs/trek/purge_expired_sign_in_codes_job.rb +15 -0
- data/app/models/concerns/trek/contentable.rb +15 -1
- data/app/models/concerns/trek/users/sign_in_code.rb +70 -0
- data/app/models/concerns/trek/users/sign_in_lockout.rb +4 -2
- data/app/policies/trek/security_check_policy.rb +8 -0
- data/app/uploaders/image_uploader.rb +77 -15
- data/app/views/trek/panels/links/_form.html.slim +2 -4
- data/app/views/trek/panels/prompts/create.turbo_stream.slim +0 -1
- data/config/locales/trek.en.yml +97 -11
- data/config/locales/trek.fr.yml +97 -11
- data/docs/.vitepress/config.mjs +5 -1
- data/docs/background-jobs.md +74 -0
- data/docs/content-editor.md +219 -0
- data/docs/customize.md +2 -0
- data/docs/deploy.md +69 -6
- data/docs/getting-started.md +16 -18
- data/docs/index.md +2 -2
- data/docs/personal-data.md +61 -0
- data/docs/proxies.md +2 -2
- data/docs/reference/components.md +4 -4
- data/docs/reference/concerns/contentable.md +10 -4
- data/docs/reference/concerns/formattable.md +1 -1
- data/docs/reference/concerns/fragmentable.md +12 -6
- data/docs/reference/concerns/orderable.md +2 -2
- data/docs/reference/concerns/search-engine-optimizable.md +1 -1
- data/docs/reference/concerns/searchable.md +14 -1
- data/docs/reference/concerns/sectionable.md +7 -3
- data/docs/reference/concerns/versionable.md +1 -1
- data/docs/reference/controllers.md +33 -1
- data/docs/reference/environment-variables.md +3 -2
- data/docs/reference/formatters.md +4 -31
- data/docs/reference/forms.md +7 -4
- data/docs/reference/generators/admin-user.md +1 -1
- data/docs/reference/generators/audit-log.md +12 -13
- data/docs/reference/generators/install.md +23 -11
- data/docs/reference/generators/public-accounts.md +159 -0
- data/docs/reference/generators/scaffold.md +28 -9
- data/docs/reference/generators/security-headers.md +5 -4
- data/docs/reference/generators/taxonomies.md +1 -1
- data/docs/reference/icons.md +5 -3
- data/docs/reference/index.md +10 -7
- data/docs/reference/models/current.md +5 -3
- data/docs/reference/models/page-version.md +1 -1
- data/docs/reference/models/user.md +7 -8
- data/docs/reference/uploaders.md +25 -0
- data/docs/reference/validators.md +1 -1
- data/docs/security.md +30 -9
- data/docs/what-is-trek.md +4 -4
- data/lib/generators/trek/USAGE +1 -1
- data/lib/generators/trek/audit_log_generator.rb +62 -0
- data/lib/generators/trek/helpers.rb +17 -0
- data/lib/generators/trek/install/admin/routes_generator.rb +2 -1
- data/lib/generators/trek/install/admin/security_check_generator.rb +36 -0
- data/lib/generators/trek/install/admin/users_generator.rb +6 -1
- data/lib/generators/trek/install/audit_log_generator.rb +9 -45
- data/lib/generators/trek/install/ci_generator.rb +19 -0
- data/lib/generators/trek/install/good_job_generator.rb +161 -0
- data/lib/generators/trek/install/model_specs_generator.rb +3 -3
- data/lib/generators/trek/install/postcss_generator.rb +1 -2
- data/lib/generators/trek/install/ruby_generator.rb +1 -1
- data/lib/generators/trek/install/scalingo_generator.rb +7 -45
- data/lib/generators/trek/install/translations_generator.rb +1 -2
- data/lib/generators/trek/install_generator.rb +18 -2
- data/lib/generators/trek/public_accounts_generator.rb +294 -0
- data/lib/generators/trek/scaffold_generator.rb +22 -21
- data/lib/generators/trek/scalingo_generator.rb +67 -0
- data/lib/generators/trek/templates/.gitlab-ci.yml +10 -1
- data/lib/generators/trek/templates/AGENTS.md +2 -2
- data/lib/generators/trek/templates/Makefile +1 -0
- data/lib/generators/trek/templates/config/i18n-tasks.yml.erb +0 -8
- data/lib/generators/trek/templates/controllers/admin/password_renewals_controller.rb +11 -0
- data/lib/generators/trek/templates/controllers/admin/security_checks_controller.rb +11 -0
- data/lib/generators/trek/templates/controllers/admin/user_sessions_controller.rb +1 -1
- data/lib/generators/trek/templates/controllers/admin/users_controller.rb +0 -8
- data/lib/generators/trek/templates/controllers/concerns/trek/authentication.rb +13 -4
- data/lib/generators/trek/templates/initializers/content_security_policy.rb +3 -2
- data/lib/generators/trek/templates/initializers/good_job.rb.tt +40 -0
- data/lib/generators/trek/templates/jobs/mail_delivery_job.rb +6 -0
- data/lib/generators/trek/templates/layouts/admin.html.slim +10 -0
- data/lib/generators/trek/templates/mailers/admin_mailer.rb +4 -2
- data/lib/generators/trek/templates/package.json.tt +1 -1
- data/lib/generators/trek/templates/policies/security_check.rb +4 -0
- data/lib/generators/trek/templates/public_accounts/api/authentication.rb.tt +76 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/accounts_controller.rb.tt +22 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/active_sessions_controller.rb.tt +21 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/base_controller.rb.tt +71 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/email_changes_controller.rb.tt +55 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/email_confirmations_controller.rb.tt +19 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/password_resets_controller.rb.tt +28 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/passwords_controller.rb.tt +17 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/registrations_controller.rb.tt +17 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/sessions_controller.rb.tt +57 -0
- data/lib/generators/trek/templates/public_accounts/api/controllers/sign_in_codes_controller.rb.tt +20 -0
- data/lib/generators/trek/templates/public_accounts/jobs/sign_in_code_job.rb.tt +23 -0
- data/lib/generators/trek/templates/public_accounts/locales/accounts.en.yml.tt +215 -0
- data/lib/generators/trek/templates/public_accounts/locales/accounts.fr.yml.tt +215 -0
- data/lib/generators/trek/templates/public_accounts/mailers/account_mailer.rb.tt +85 -0
- data/lib/generators/trek/templates/public_accounts/migrations/create_accounts.rb.tt +46 -0
- data/lib/generators/trek/templates/public_accounts/models/account/session.rb.tt +47 -0
- data/lib/generators/trek/templates/public_accounts/models/account/sign_in_code.rb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/models/account.rb.tt +87 -0
- data/lib/generators/trek/templates/public_accounts/spec/api/accounts_spec.rb.tt +90 -0
- data/lib/generators/trek/templates/public_accounts/spec/api/sign_ins_spec.rb.tt +188 -0
- data/lib/generators/trek/templates/public_accounts/spec/models/account/sign_in_code_spec.rb.tt +66 -0
- data/lib/generators/trek/templates/public_accounts/spec/models/account_spec.rb.tt +129 -0
- data/lib/generators/trek/templates/public_accounts/spec/web/accounts_spec.rb.tt +126 -0
- data/lib/generators/trek/templates/public_accounts/spec/web/authentication_spec.rb.tt +43 -0
- data/lib/generators/trek/templates/public_accounts/spec/web/sign_ins_spec.rb.tt +237 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.en.html.slim.tt +10 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.en.text.erb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.fr.html.slim.tt +13 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change.fr.text.erb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.en.html.slim.tt +9 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.en.text.erb.tt +11 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.fr.html.slim.tt +11 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_change_code.fr.text.erb.tt +11 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.en.html.slim.tt +10 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.en.text.erb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.fr.html.slim.tt +10 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/email_confirmation.fr.text.erb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.en.html.slim.tt +10 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.en.text.erb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.fr.html.slim.tt +13 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/password_reset.fr.text.erb.tt +8 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.en.html.slim.tt +9 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.en.text.erb.tt +11 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.fr.html.slim.tt +9 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_code.fr.text.erb.tt +11 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.en.html.slim.tt +23 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.en.text.erb.tt +14 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.fr.html.slim.tt +24 -0
- data/lib/generators/trek/templates/public_accounts/views/mailer/sign_in_locked.fr.text.erb.tt +14 -0
- data/lib/generators/trek/templates/public_accounts/web/authentication.rb.tt +97 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/accounts_controller.rb.tt +33 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/active_sessions_controller.rb.tt +15 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/base_controller.rb.tt +52 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/email_changes_controller.rb.tt +85 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/email_confirmations_controller.rb.tt +19 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/password_resets_controller.rb.tt +41 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/passwords_controller.rb.tt +23 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/registrations_controller.rb.tt +24 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/sessions_controller.rb.tt +85 -0
- data/lib/generators/trek/templates/public_accounts/web/controllers/sign_in_codes_controller.rb.tt +32 -0
- data/lib/generators/trek/templates/public_accounts/web/views/_flash.html.slim.tt +5 -0
- data/lib/generators/trek/templates/public_accounts/web/views/accounts/show.html.slim.tt +52 -0
- data/lib/generators/trek/templates/public_accounts/web/views/email_changes/edit.html.slim.tt +17 -0
- data/lib/generators/trek/templates/public_accounts/web/views/email_changes/new.html.slim.tt +15 -0
- data/lib/generators/trek/templates/public_accounts/web/views/password_resets/edit.html.slim.tt +29 -0
- data/lib/generators/trek/templates/public_accounts/web/views/password_resets/new.html.slim.tt +15 -0
- data/lib/generators/trek/templates/public_accounts/web/views/passwords/edit.html.slim.tt +28 -0
- data/lib/generators/trek/templates/public_accounts/web/views/registrations/new.html.slim.tt +30 -0
- data/lib/generators/trek/templates/public_accounts/web/views/sessions/new.html.slim.tt +40 -0
- data/lib/generators/trek/templates/public_accounts/web/views/sign_in_codes/new.html.slim.tt +17 -0
- data/lib/generators/trek/templates/spec/jobs/mail_delivery_job_spec.rb +11 -0
- data/lib/generators/trek/templates/spec/mailers/admin_mailer_spec.rb +10 -0
- data/lib/generators/trek/templates/spec/requests/admin/fragments_spec.rb +1 -1
- data/lib/generators/trek/templates/spec/requests/admin/good_job_spec.rb +34 -0
- data/lib/generators/trek/templates/spec/requests/admin/pages_spec.rb +12 -1
- data/lib/generators/trek/templates/spec/requests/admin/panels_spec.rb +16 -0
- data/lib/generators/trek/templates/spec/requests/admin/password_renewal_spec.rb +2 -2
- data/lib/generators/trek/templates/spec/requests/admin/security_checks_spec.rb +24 -0
- data/lib/generators/trek/templates/spec/requests/admin/sign_in_lockout_spec.rb +1 -1
- data/lib/generators/trek/templates/spec/requests/admin/sign_in_notices_spec.rb +33 -0
- data/lib/generators/trek/templates/spec/requests/admin/user_sessions_spec.rb +2 -2
- data/lib/generators/trek/templates/views/admin/pages/_form.html.slim +1 -1
- data/lib/generators/trek/templates/views/admin/security_checks/show.html.slim +9 -0
- data/lib/generators/trek/templates/views/admin/user_password_resets/edit.html.slim +6 -1
- data/lib/generators/trek/templates/views/admin/user_sessions/new.html.slim +4 -1
- data/lib/generators/trek/templates/views/admin/users/index.html.slim +1 -1
- data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.en.html.slim +1 -1
- data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.en.text.erb +1 -1
- data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.fr.html.slim +1 -1
- data/lib/generators/trek/templates/views/admin_mailer/new_sign_in.fr.text.erb +1 -1
- data/lib/tasks/trek/attachments.rake +12 -0
- data/lib/tasks/trek/security.rake +10 -0
- data/lib/trek/csp_reports.rb +22 -4
- data/lib/trek/disposable_email_domains.rb +9 -20
- data/lib/trek/engine.rb +5 -0
- data/lib/trek/json_compatibility.rb +20 -0
- data/lib/trek/security_check.rb +241 -0
- data/lib/trek/stored_image_metadata.rb +88 -0
- data/lib/trek/typography_formatter.rb +35 -4
- data/lib/trek/version.rb +1 -1
- data/lib/trek.rb +2 -1
- data/package.json +16 -13
- data/postcss.config.js +0 -3
- data/trek.gemspec +6 -7
- data/vitest.config.mjs +24 -0
- data/yarn.lock +1667 -1010
- metadata +122 -33
|
@@ -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
|
```
|
|
@@ -15,9 +15,11 @@ Trek provides an install generator, that will:
|
|
|
15
15
|
- create the relevant policies
|
|
16
16
|
- generate and run the relevant migrations
|
|
17
17
|
|
|
18
|
+
It ends with what to do next: create an admin user, start the server, and the generators it leaves for later, to run as the app needs them: [`trek:scaffold`](/reference/generators/scaffold), [`trek:taxonomies`](/reference/generators/taxonomies), [`trek:audit_log`](/reference/generators/audit-log), [`trek:public_accounts`](/reference/generators/public-accounts) and [`trek:scalingo`](/deploy).
|
|
19
|
+
|
|
18
20
|
## Sub-generators
|
|
19
21
|
|
|
20
|
-
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`.
|
|
21
23
|
|
|
22
24
|
| Area | What gets set up |
|
|
23
25
|
| --- | --- |
|
|
@@ -25,19 +27,18 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
|
|
|
25
27
|
| Authorization | ActionPolicy and the base policies |
|
|
26
28
|
| Models | `User`, `Page`, `PagePath`, `PageVersion`, `Fragment`, `MenuNode`, `ExternalLink`, `Current` — with migrations |
|
|
27
29
|
| Attachments | Shrine configuration and the uploaders |
|
|
28
|
-
| Emails | Postmark and
|
|
30
|
+
| Emails | Postmark, `AdminMailer` (invitations, new sign-in and lockout alerts) and `Admin::PasswordsMailer` (password resets) |
|
|
29
31
|
| I18n | rails-i18n, Mobility, i18n-tasks and the locale files |
|
|
30
|
-
| 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 |
|
|
31
33
|
| Pagination | Kaminari |
|
|
32
34
|
| Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
|
|
33
|
-
| Linting |
|
|
34
|
-
| Security | Brakeman, bundler-audit,
|
|
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
|
+
| 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) |
|
|
35
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 |
|
|
36
|
-
| Specs | RSpec, and specs for
|
|
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 |
|
|
37
40
|
| N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
|
|
38
|
-
| CI | GitLab CI configuration: specs, linters, Brakeman, bundler-audit, and, commented out, a [Software Bill of Materials](#software-bill-of-materials) |
|
|
39
|
-
| Deployment | Scalingo files (`trek:install:scalingo`, run on demand) — see [Deploying to Scalingo](/deploy) |
|
|
40
|
-
| Audit log | The `AuditLog` model recording the admin's requests, and its admin list (`trek:install:audit_log`, run on demand) — see [Audit log](/reference/generators/audit-log) |
|
|
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) |
|
|
41
42
|
|
|
42
43
|
## ENV variables read by the installer
|
|
43
44
|
|
|
@@ -45,7 +46,18 @@ Define these **before** running the installer to have them injected automaticall
|
|
|
45
46
|
|
|
46
47
|
- `POSTMARK_API_TOKEN` — injected into the Rails credentials for email delivery
|
|
47
48
|
- `APPSIGNAL_PUSH_API_KEY` — injected into the Rails credentials for error tracking and performance monitoring
|
|
48
|
-
|
|
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.
|
|
49
61
|
|
|
50
62
|
## Software Bill of Materials
|
|
51
63
|
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# Public accounts
|
|
2
|
+
|
|
3
|
+
```sh
|
|
4
|
+
bin/rails g trek:public_accounts Customer [--sign-in=code|password] [--invite-only] [--api] [--path=customers] [--model-only]
|
|
5
|
+
bin/rails db:migrate
|
|
6
|
+
```
|
|
7
|
+
|
|
8
|
+
Accounts for the people using the site or the mobile app (customers, members, readers…), apart from the admin's [`User`](/reference/models/user). They have their own model, table, sessions and sign-in, so nothing public can reach a staff account: signing up, deleting inactive accounts or merging duplicates only ever sees public accounts, and a public session never opens the admin.
|
|
9
|
+
|
|
10
|
+
The name is required, and is the app's own: `User` is the admin's account, so the generator refuses it, a namespaced name, and the names of Trek's models. Pick the word of the app's domain (`Customer`, `Member`, `Reader`…).
|
|
11
|
+
|
|
12
|
+
| Option | Effect |
|
|
13
|
+
| --- | --- |
|
|
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) |
|
|
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 |
|
|
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 |
|
|
18
|
+
| `--path=customers` | Puts the routes under a path, e.g. `/customers/sign-in`: for an app with two kinds of public accounts |
|
|
19
|
+
| `--model-only` | Neither pages nor endpoints: see [Model only](#model-only). Can't be combined with `--api` or `--path` |
|
|
20
|
+
|
|
21
|
+
## Model only
|
|
22
|
+
|
|
23
|
+
With `--model-only`, the generator adds the models, their migration, `Current.customer_session` and `Current.customer`, the mailer, its job for codes, the locales and the model specs, but no controllers, pages, routes nor JWT. It's for an app whose sign-in is its own, e.g. an API ported from another app that its mobile app already calls: the app keeps its endpoints and tokens, on top of `Customer` and its rules (passwords, lockout, sessions, inactive accounts).
|
|
24
|
+
|
|
25
|
+
The app then creates and finds the `Customer::Session` rows itself, or ignores them, and sets `Current.customer_session`. With passwords, the emailed links point at the app's domain (`https://<host>/account/confirm?token=…`, `/password-reset?token=…`, `/account/email?token=…`), or at `CUSTOMERS_APP_LINKS_URL`, as for the API: the app's own pages or mobile app handle them.
|
|
26
|
+
|
|
27
|
+
## Signing in with an emailed code
|
|
28
|
+
|
|
29
|
+
1. The person types their email; the app emails them a 6-digit code. It answers the same whether or not the email has an account (ANSSI guide on passwords, R14).
|
|
30
|
+
2. They type the code: it signs them in to the email's account, created the first time. Signing up is signing in.
|
|
31
|
+
|
|
32
|
+
A code is valid for 10 minutes, for 5 tries (the right one included), and once. A new code replaces the earlier one. Only an HMAC of the code is stored, keyed on the app's `secret_key_base`, and the code is created in the job sending the email, so it's never in the job queue either. Change `validity` and `max_attempts` on `Customer::SignInCode`.
|
|
33
|
+
|
|
34
|
+
A new email address is confirmed the same way: a code sent to it.
|
|
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
|
+
|
|
42
|
+
## Signing in with a password
|
|
43
|
+
|
|
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.
|
|
45
|
+
- **Failed sign-ins** lock signing in as for the admin (`Trek::Users::SignInLockout`), and `CustomerMailer#sign_in_locked` tells the account.
|
|
46
|
+
- **A forgotten password** is reset by a link, valid 15 minutes and used up by the new password (`has_secure_password`'s `password_reset_token`), which signs out every session. Asking for one answers the same whether or not the email has an account.
|
|
47
|
+
- **Changing the password** needs a recent sign-in (15 minutes, `Customer::Session::RECENT`), and signs out the other sessions.
|
|
48
|
+
- **A new email address** is kept in `unconfirmed_email` until the link sent to it, valid an hour, is followed.
|
|
49
|
+
|
|
50
|
+
## Rate limits
|
|
51
|
+
|
|
52
|
+
Against guessing and flooding, each IP address may try to sign in 10 times in 3 minutes (5 with a password) and fail 20 times an hour, and ask for 10 emails (codes, links) in 15 minutes; each address gets at most 5 emails an hour. The limits are counted in `Rails.cache`, which must be shared between servers (see [Failed sign-ins](/reference/models/user#failed-sign-ins)).
|
|
53
|
+
|
|
54
|
+
## Sessions
|
|
55
|
+
|
|
56
|
+
| | Website | API (`--api`) |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| Held by | a signed `customer_session_id` cookie (`HttpOnly`, `SameSite=Lax`) | a JWT the app sends as `Authorization: Bearer …` |
|
|
59
|
+
| Expires | after 30 days without a request, and a year after signing in | the same, checked on the session row: the JWT only names it |
|
|
60
|
+
| Signing out | deletes the session and the cookie | deletes the session, and the JWT stops working |
|
|
61
|
+
|
|
62
|
+
Both are `Customer::Session` rows (`customer_sessions`), listed on the account, where the person can sign out the others. Change `idle_timeout` and `lifetime` on `Customer::Session` ([Trek::Users::SessionLifetime](/reference/models/user#sessions)). The JWT is signed with HS256 and a key derived from `secret_key_base`, and carries the session's id (`sub`) and the end of its lifetime (`exp`): unlike a self-contained token, it can be revoked.
|
|
63
|
+
|
|
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`.
|
|
65
|
+
|
|
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
|
+
```
|
|
78
|
+
|
|
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.
|
|
80
|
+
|
|
81
|
+
## What the generator adds
|
|
82
|
+
|
|
83
|
+
- `Customer` and `Customer::Session`, `Customer::SignInCode` for codes, and a migration creating their tables
|
|
84
|
+
- `Current.customer_session`, and `Current.customer`
|
|
85
|
+
- `Customers::Authentication`, and the controllers: under `Customers::` with pages for a website, under `Api::V1::Customers::` for the API
|
|
86
|
+
- `CustomerMailer` with its views in English and French, and `Customers::SignInCodeJob` for codes
|
|
87
|
+
- `config/locales/customers.{en,fr}.yml`
|
|
88
|
+
- the routes, on paths of their own (below), so renaming the model keeps them
|
|
89
|
+
- specs, when the app has a `spec` directory
|
|
90
|
+
|
|
91
|
+
### Website
|
|
92
|
+
|
|
93
|
+
`Customers::Authentication` is included in `ApplicationController`, so every page may use:
|
|
94
|
+
|
|
95
|
+
| Helper | Returns |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| `current_customer`, `customer_signed_in?` | the signed-in customer, if any |
|
|
98
|
+
| `staff_user` | the admin's user signed in in this browser, when privileged, for previews and links to the admin on the site. Read only: it neither extends nor ends their admin session, and never signs a customer in |
|
|
99
|
+
|
|
100
|
+
A page for customers only calls `before_action :require_customer`, which sends the others to sign in and brings them back after.
|
|
101
|
+
|
|
102
|
+
| Path | Page |
|
|
103
|
+
| --- | --- |
|
|
104
|
+
| `GET /sign-in` | the sign-in form (`customer_sign_in_path`): the email for a code, or the email and password |
|
|
105
|
+
| `GET /sign-in/code` | the code form (codes) |
|
|
106
|
+
| `GET /sign-up` | the sign-up form (passwords) |
|
|
107
|
+
| `GET /password-reset/new` | asking for a link to choose a new password (passwords) |
|
|
108
|
+
| `GET /account/confirm?token=…` | the link confirming the email (passwords) |
|
|
109
|
+
| `DELETE /sign-out` | signs out |
|
|
110
|
+
| `GET /account` | the account: name, email, password, signed-in browsers, deletion (`customer_account_path`) |
|
|
111
|
+
| `GET /account/email/new` | changing the email, confirmed by a code or a link sent to the new address |
|
|
112
|
+
| `GET /account/password/edit` | changing the password (passwords) |
|
|
113
|
+
|
|
114
|
+
The pages render in the site's layout, unstyled, with their notices in `app/views/customers/_flash.html.slim`: move those to the layout if it shows flash messages.
|
|
115
|
+
|
|
116
|
+
### API
|
|
117
|
+
|
|
118
|
+
The endpoints are the API's first version, under `/api/v1`, so that a later version can be served next to them while older releases of the mobile app still call these. Every endpoint answers JSON; an error comes as `{ "error": "invalid_code", "message": "…" }`, the message in the request's locale.
|
|
119
|
+
|
|
120
|
+
| Endpoint | Body | Answer |
|
|
121
|
+
| --- | --- | --- |
|
|
122
|
+
| `POST /api/v1/sign-in` | codes: `email`; passwords: `email`, `password` | codes: 202, a code is emailed; passwords: 201, `{ token, customer }` |
|
|
123
|
+
| `POST /api/v1/sign-in/code` | `email`, `otp` | 201, `{ token, customer }` (codes) |
|
|
124
|
+
| `POST /api/v1/sign-up` | `email`, `password`, `name` | 201, `{ token, customer }` (passwords) |
|
|
125
|
+
| `POST /api/v1/password-reset` | `email` | 202, a link is emailed if the email has an account (passwords) |
|
|
126
|
+
| `PATCH /api/v1/password-reset` | `token`, `password` | 204 (passwords) |
|
|
127
|
+
| `POST`, `PATCH /api/v1/account/confirmation` | `token` for `PATCH` | sends the confirmation link again; confirms the email (passwords) |
|
|
128
|
+
| `DELETE /api/v1/session` | | 204, signs out |
|
|
129
|
+
| `GET`, `PATCH`, `DELETE /api/v1/account` | `name` | the account; deleting needs a recent sign-in |
|
|
130
|
+
| `POST /api/v1/account/email` | `email` | 202, a code or a link is emailed to the new address |
|
|
131
|
+
| `PATCH /api/v1/account/email` | codes: `email`, `otp`; passwords: `token` | the account, with its new email; 409 when another account has it |
|
|
132
|
+
| `PATCH /api/v1/account/password` | `password` | 204 (passwords); needs a recent sign-in |
|
|
133
|
+
| `GET /api/v1/account/sessions` | | the signed-in devices, `current` for this one |
|
|
134
|
+
| `DELETE /api/v1/account/sessions/:id`, `/others` | | 204 |
|
|
135
|
+
|
|
136
|
+
With passwords, the emailed links point at the app's domain (`https://<host>/account/confirm?token=…`, `/password-reset?token=…`, `/account/email?token=…`), or at `CUSTOMERS_APP_LINKS_URL`: the mobile app opens them (iOS universal links, Android app links) and sends their `token` to the endpoints above.
|
|
137
|
+
|
|
138
|
+
## Audit log
|
|
139
|
+
|
|
140
|
+
When the app has the [audit log](/reference/generators/audit-log), the account controllers write to it too: sign-ins, failed or not, sign-ups, code and link requests (with no actor), and account changes, the customer being the actor.
|
|
141
|
+
|
|
142
|
+
## Inactive accounts
|
|
143
|
+
|
|
144
|
+
`Customer.inactive_since(time)` lists the accounts with no request since `time` (`last_activity_at`, written at most every 5 minutes), e.g. for a job deleting them. It can only ever list customers.
|
|
145
|
+
|
|
146
|
+
## Upgrading Trek
|
|
147
|
+
|
|
148
|
+
The generated files are the app's own: upgrading Trek never changes them. On each upgrade, check:
|
|
149
|
+
|
|
150
|
+
- **The CHANGELOG,** for entries on what the generated code relies on in the gem: `Trek::Users::SessionLifetime`, `Trek::Users::SignInCode` (codes), `Trek::Users::SignInLockout` and `Trek::Users::PasswordPolicy` (passwords), `Trek::PurgeExpiredSessionsJob`, `Trek::ResolveSessionHostnameJob` and `Trek::Auditable`.
|
|
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:
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
bin/rails g trek:public_accounts Customer --force # plus the options it was generated with
|
|
155
|
+
git diff
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Running it again adds nothing already there: no second migration, route or `Current` attribute.
|
|
159
|
+
- **The admin's session,** which `staff_user` reads: its `session_id` cookie and `User::Session`, in `Customers::Authentication#staff_user`. An upgrade note says when they change.
|
|
@@ -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
|
|
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`…)
|
|
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
|
-
##
|
|
34
|
+
## The model
|
|
34
35
|
|
|
35
|
-
The
|
|
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
|
-
#
|
|
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
|
|
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 |
|
|
@@ -41,7 +42,7 @@ The policy only **reports** violations at first (`config.content_security_policy
|
|
|
41
42
|
|
|
42
43
|
### Violation reports
|
|
43
44
|
|
|
44
|
-
Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. It logs each one too (`[CSP] script-src-elem blocked https://
|
|
45
|
+
Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. To tell what was blocked, each report is also tagged with the browser's user agent and, when the browser gives them, where it happened (`source`: the file's URL, without its query, and the line) and the `sample`: the first 40 characters of an inline script, which the policy asks for with `'report-sample'` (`policy.script_src :self, :report_sample`). Tags are cut to 255 characters, as AppSignal drops longer ones. It logs each one too (`[CSP] script-src-elem blocked inline on /pages/team (report) at https://www.example.com/pages/team:12: "alert(1)"`), which is all an app without AppSignal gets.
|
|
45
46
|
|
|
46
47
|
It keeps the reports about the app's own pages only, and drops what browser extensions load or inject, which makes most reports and says nothing about the app. It keeps the page's path, not its query, which may carry a token, and the blocked resource's origin, not its URL. Browsers send no CSRF token nor cookie: the endpoint needs neither, and answers `204`.
|
|
47
48
|
|
data/docs/reference/icons.md
CHANGED
|
@@ -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(
|
|
6
|
+
render Trek::IconComponent.new("trek/search")
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
|
|
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.
|
data/docs/reference/index.md
CHANGED
|
@@ -4,12 +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:
|
|
12
|
-
- [
|
|
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
|
|
13
16
|
|
|
14
17
|
## Models
|
|
15
18
|
|
|
@@ -18,7 +21,7 @@ Generated into your application — they're yours to read and modify.
|
|
|
18
21
|
- [Page](/reference/models/page), [PageVersion](/reference/models/page-version), [PagePath](/reference/models/page-path)
|
|
19
22
|
- [Fragment](/reference/models/fragment)
|
|
20
23
|
- [MenuNode](/reference/models/menu-node), [ExternalLink](/reference/models/external-link)
|
|
21
|
-
- [User](/reference/models/user) (and its session
|
|
24
|
+
- [User](/reference/models/user) (and its deprecated session form model)
|
|
22
25
|
- [Tag, TagCategory & Tagging](/reference/models/tag) (with the taxonomies generator)
|
|
23
26
|
- [Current](/reference/models/current)
|
|
24
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
|
|
5
|
+
Trek uses it for per-request data:
|
|
6
6
|
|
|
7
7
|
```ruby
|
|
8
|
-
Current.
|
|
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 (
|
|
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
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
The host application's `User` model, into which Trek injects authentication (`has_secure_password` and database-backed sessions), roles, theme & locale preferences and the invitation workflow.
|
|
4
4
|
|
|
5
|
+
It is the admin's account. The site's or the mobile app's users (customers, members…) get a model of their own, apart from it: see [Public accounts](/reference/generators/public-accounts).
|
|
6
|
+
|
|
5
7
|
## Columns added by Trek
|
|
6
8
|
|
|
7
9
|
| Column | Type | Notes |
|
|
@@ -11,7 +13,7 @@ The host application's `User` model, into which Trek injects authentication (`ha
|
|
|
11
13
|
| `theme` | integer | enum, default `auto` |
|
|
12
14
|
| `locale` | string | admin UI language |
|
|
13
15
|
| `password_digest` | string | `has_secure_password` (bcrypt), required |
|
|
14
|
-
| `last_activity_at` | datetime | updated
|
|
16
|
+
| `last_activity_at` | datetime | updated while signed in, at most every 5 minutes (see [Sessions](#sessions)) |
|
|
15
17
|
| `password_changed_at` | datetime | when the password was last set, for its expiry |
|
|
16
18
|
| `password_renewal_required_at` | datetime | when an admin asked everyone for a new password (`password_renewal_required?`) |
|
|
17
19
|
| `failed_sign_in_count` | integer | failed sign-ins in a row, for the [lockout](#failed-sign-ins) |
|
|
@@ -59,7 +61,7 @@ Each signed-in browser is a `User::Session`, which `Trek::Users::SessionLifetime
|
|
|
59
61
|
| `lifetime` | 30 days | since signing in, whatever the activity; also the cookie's expiry |
|
|
60
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 |
|
|
61
63
|
|
|
62
|
-
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:
|
|
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.
|
|
63
65
|
|
|
64
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.
|
|
65
67
|
|
|
@@ -68,7 +70,7 @@ Users see their **active sessions** in a tab of their own profile: browser and s
|
|
|
68
70
|
`Trek::Users::SignIns` helps users spot a sign-in that wasn't theirs:
|
|
69
71
|
|
|
70
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;
|
|
71
|
-
- a sign-in from a **browser that never signed in as the user** emails them (`AdminMailer#new_sign_in`): date, browser, IP address, with links to change their password and to their active sessions. A browser is recognized by
|
|
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.
|
|
72
74
|
|
|
73
75
|
Set `self.new_sign_in_email = false` in the `User` model to turn the email off.
|
|
74
76
|
|
|
@@ -126,7 +128,7 @@ User.create(email: "new@example.com", role: :editor, send_invite: true)
|
|
|
126
128
|
`Trek::Users::Validations` enforces:
|
|
127
129
|
|
|
128
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)
|
|
129
|
-
- `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
|
|
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))
|
|
130
132
|
|
|
131
133
|
### Disposable email addresses
|
|
132
134
|
|
|
@@ -181,7 +183,4 @@ end
|
|
|
181
183
|
|
|
182
184
|
## Form models
|
|
183
185
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
- **`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
|
|
187
|
-
- **`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.
|
data/docs/reference/uploaders.md
CHANGED
|
@@ -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
|
|
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
|
|