paper_trail_history 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d4cf46205ebd10b78ce9d159df2a384e2b00071a80efad39bf2e79bbcb84b05
-  data.tar.gz: 7b1155089a6b7328d76d63d137fb527e0e68219da77da09f1358d824c6f2bfe5
+  metadata.gz: e8d783c6662b5a2e8b0a95cb2b3919ff0003b1e41a896299a319b57208f0cc5b
+  data.tar.gz: ff66f4f17756391bd5c7194a49c39198315ca3263ab1918e511f7e786d5554fe
 SHA512:
-  metadata.gz: 92abd0ba47e73f3980186c8f52819b58b7cdf33becc042d49703233a070c3a43a312f45d2d69ecd9bc10e67bb974675c93749f05eb528dd1806f410763e36ff4
-  data.tar.gz: f9a7cd1637b73274d866138706ad49ff1f1b1222575f4aca7dff2f8114584c9b30bcfb20f71ed731fb0af1234cb6bebef631f5eb2d23584a0bcd571dbee8cbec
+  metadata.gz: 7aca6f92cae47c07111415c234b4c3357028f997dc8325ab9ba20ad79308bba5e86557a63f188ad8166a495798cfc6d6685908a532e6aef24b32787340ad080b
+  data.tar.gz: 7981eea56e36d5d74c37e7445a29b0f4f8148a8ed5d4dd8182d17063e8de39c610c127495f5ba8c2818960896c1e1839f8256db4a42603d11268094e6adf5da8

data/README.md

@@ -34,14 +34,239 @@ Rails.application.routes.draw do
 end
 ```
 
+Then configure access control - **mounting alone is not enough**, see below.
+
+## Security
+
+> [!IMPORTANT]
+> This engine has **no authentication of its own**. It exposes the complete audit
+> trail of every versioned model - including historical values of attributes that
+> may since have been changed or redacted - and it exposes a `PATCH` endpoint that
+> overwrites live records. Treat the mount point like an admin console.
+
+`PaperTrailHistory::ApplicationController` does **not** inherit from your
+application's `ApplicationController`, so none of your `before_action` filters run
+inside the engine. You have to grant access explicitly.
+
+Since 0.3.0 the engine **refuses every request with `403 Forbidden` unless you
+configure it**. Development and test environments stay open (with a log warning) so
+that the dummy app and your test suite keep working without an initializer.
+
+### Configuration
+
+Create `config/initializers/paper_trail_history.rb`:
+
+```ruby
+PaperTrailHistory.configure do |config|
+  # Option A: inherit from a controller that already authenticates.
+  # The engine keeps its own layout, only the filters are inherited.
+  config.parent_controller = 'Admin::BaseController'
+
+  # Option B: run your own filter. Executed via instance_exec in the controller,
+  # so current_user, session, redirect_to, head and main_app.* are all available.
+  config.authenticate_with = -> { redirect_to main_app.root_path unless current_user&.admin? }
+
+  # Optional: a separate gate for the destructive restore action.
+  # This one is a PREDICATE - return true to allow, false to deny.
+  # If unset, anyone who passes authentication may restore.
+  config.authorize_restore_with = -> { current_user.owner? }
+end
+```
+
+### Assets and Content Security Policy
+
+The interface uses Bootstrap, loaded from jsDelivr by default and pinned with a
+subresource integrity hash so a tampered file is rejected by the browser. The
+engine's own inline `<style>` and `<script>` carry the CSP nonce when your
+application generates one, so a nonce-based policy works without `unsafe-inline`.
+
+To serve the files yourself - required for an air-gapped network, or a policy
+that allows no third-party origin - point them at your own assets and drop the
+integrity hashes:
+
+```ruby
+config.assets = {
+  bootstrap_css:       { href: '/assets/bootstrap.css' },
+  bootstrap_icons_css: { href: '/assets/bootstrap-icons.css' },
+  bootstrap_js:        { href: '/assets/bootstrap.bundle.js' }
+}
+```
+
+> [!WARNING]
+> If your nonce generator returns an empty string the browser rejects the whole
+> nonce source and blocks all inline style and script. Rails' commented-out
+> suggestion, `request.session.id.to_s`, does exactly that on a request with no
+> session yet. Prefer something that always yields a value, e.g.
+> `->(_request) { SecureRandom.base64(16) }`.
+
+### Models with a non-integer primary key
+
+The engine looks records up by the model's own primary key, so a model using a
+UUID or any other custom key works.
+
+> [!NOTE]
+> PaperTrail's generated `versions` table declares `item_id` as `bigint`. A UUID
+> written into that column becomes `0`, and the version history for such a model
+> stays empty. This is a property of your versions table, not of this engine - if
+> you version models with non-integer keys, `item_id` has to be a string column.
+
+### Single table inheritance
+
+PaperTrail records the **base class** name in `item_type`, so a version created
+by `Admin < User` is stored as `"User"`. The engine looks versions up by base
+class and narrows them with PaperTrail's optional `item_subtype` column, which
+holds the real class name.
+
+If your versions table has an `item_subtype` column, each STI subclass shows
+exactly its own history, and the base class shows all of it (matching
+ActiveRecord's own STI semantics). Without that column the subtypes are
+indistinguishable in the data, so a subclass falls back to showing its base
+class's versions. To add it:
+
+```ruby
+add_column :versions, :item_subtype, :string
+add_index  :versions, %i[item_type item_subtype]
+```
+
+### Version counts on the model list
+
+The model list does **not** show a version count per model, because building that
+column costs one `COUNT` query per version table and a count reads the whole
+table. An application that gives each model its own version table therefore pays
+one full table read per model, on its landing page. With ~120 models and tables
+in the millions of rows, that is the difference between an instant page and a
+page that takes tens of seconds.
+
+Each model's own page always shows its count - that is a single query.
+
+If your installation is small enough not to care, turn the column on:
+
+```ruby
+config.show_version_counts = true
+```
+
+> [!TIP]
+> No index makes this faster. When a model has its own version table every row
+> shares the same `item_type`, so an index on it cannot narrow the scan —
+> counting is inherently proportional to the number of rows.
+
+### Page size
+
+Version tables grow without bound, so the engine reads one page at a time rather
+than loading a model's entire history into memory. The default is 25 rows:
+
+```ruby
+config.page_limit = 50
+```
+
+Pagination uses [Pagy](https://github.com/ddnexus/pagy). The limit is passed per
+query rather than written into `Pagy::OPTIONS`, so mounting this engine does not
+change pagination defaults elsewhere in your application.
+
+### Translations
+
+Every string in the interface goes through I18n. The gem ships **English and
+German**; dates and times use per-locale format strings, so each language orders
+them its own way.
+
+To translate the interface into another language, add a locale file under the
+`paper_trail_history` scope - see `config/locales/en.yml` in this gem for the
+full set of keys. To override individual strings, define the same key in your
+application; your locale files load after the engine's and win.
+
+> [!NOTE]
+> Because only `en` and `de` ship, an application running under a third locale
+> gets missing-translation errors unless I18n fallbacks are enabled:
+> ```ruby
+> config.i18n.fallbacks = [:en]
+> ```
+
+### Redacting sensitive attributes
+
+The interface shows every attribute of a record, and every before/after value in
+a version diff. Without redaction that means password digests, API tokens and
+session keys - including *historical* values that have since been rotated.
+
+By default the engine hides whatever your application already hides from its
+logs, i.e. `Rails.application.config.filter_parameters`. Attributes matched by
+that list render as `[FILTERED]` on both the record page and the diff. To hide
+more:
+
+```ruby
+config.filter_attributes += [:internal_note, /_secret\z/]
+```
+
+The list accepts everything `ActiveSupport::ParameterFilter` accepts - symbols,
+strings (substring match), regular expressions and procs - and matching is
+delegated to that class, so it behaves exactly like Rails log filtering.
+
+> [!NOTE]
+> Rails' default `filter_parameters` includes `:email`, so email addresses are
+> redacted out of the box. Set `config.filter_attributes` explicitly if that is
+> not what you want.
+
+Either `parent_controller` or `authenticate_with` satisfies the check; you can use
+both. Note the asymmetry: `authenticate_with` is a **filter** (halt the chain
+yourself with `redirect_to`/`head`, which lets you pass Devise's
+`authenticate_user!` straight in), while `authorize_restore_with` is a
+**predicate** that returns a boolean.
+
+`parent_controller` is read once, when Rails first loads the engine controller.
+Set it in an initializer - changing it at runtime has no effect.
+
+### Route-level protection
+
+Configuration composes with a route constraint, and using both is a good idea:
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount PaperTrailHistory::Engine, at: '/revisions'
+end
+```
+
+### Running without authentication
+
+If a different layer protects the mount point (a VPN, a reverse proxy, an
+IP allowlist), opt out explicitly:
+
+```ruby
+config.allow_unauthenticated_access = true
+```
+
 ## Prerequisites
 
 This engine requires:
-- Rails >= 7.2
+- Ruby >= 3.3.0
+- Rails >= 8.0
 - PaperTrail >= 15.0 (configured with `has_paper_trail` in your models)
+- Pagy ~> 43.0 (installed automatically, see the note in the changelog)
 
 Make sure you have PaperTrail properly configured in your Rails application before using this engine.
 
+### YAML deserialization (required for restoring)
+
+PaperTrail stores the previous state of a record as YAML. Since Rails 7.1, Rails
+loads only an explicitly permitted set of classes out of a YAML column, and that
+set does **not** include `ActiveSupport::TimeWithZone`. Every model with
+`created_at`/`updated_at` therefore fails to reify, and restoring dies with:
+
+```
+Tried to load unspecified class: ActiveSupport::TimeWithZone
+```
+
+Browsing history is unaffected - only restoring breaks. Permit the types your
+models actually store, in `config/application.rb`:
+
+```ruby
+config.active_record.yaml_column_permitted_classes = [
+  Symbol, Date, Time, ActiveSupport::TimeWithZone, ActiveSupport::TimeZone, BigDecimal
+]
+```
+
+Add any other class your models serialize (for example `ActiveSupport::HashWithIndifferentAccess`).
+If a class is missing, the engine reports which setting to change instead of
+showing the raw Psych error.
+
 ## Usage
 
 After mounting the engine, navigate to `/revisions` (or whatever path you chose) in your browser to access the interface.
@@ -57,7 +282,7 @@ After mounting the engine, navigate to `/revisions` (or whatever path you chose)
    - View all versions for a specific model
    - Filter by event type, user, date range
    - Search within version content
-   - Pagination support
+   - Pagination (25 rows per page by default, see `config.page_limit`)
 
 3. **Record Versions** (`/revisions/models/:model_name/:record_id/versions`)
    - View version history for a specific record
@@ -139,6 +364,22 @@ bundle exec rake test TESTOPTS="-v"
 bundle exec rubocop
 ```
 
+### API Documentation
+
+The public API is documented with YARD. CI fails if a public object loses its
+documentation, so new API needs a docstring to merge.
+
+```bash
+# Generate HTML docs into doc/
+bundle exec rake yard
+
+# List anything public that is undocumented (this is what CI runs)
+bundle exec rake yard:coverage
+```
+
+Internal helpers are tagged `@api private` and are excluded from both the
+generated docs and the coverage gate.
+
 ### Testing Different Components
 
 ```bash
@@ -178,14 +419,14 @@ The dummy app includes:
 For comprehensive compatibility testing, use the provided Gemfiles:
 
 ```bash
-# Test against Rails 7.2
-BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rake test
-
 # Test against Rails 8.0
-BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle install  
+BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle exec rake test
 
+# Test against Rails 8.1
+BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle exec rake test
+
 # Test against Rails main branch
 BUNDLE_GEMFILE=gemfiles/rails_main.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/rails_main.gemfile bundle exec rake test

data/Rakefile

@@ -26,4 +26,67 @@ namespace :test do
   end
 end
 
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new(:yard)
+
+  namespace :yard do
+    desc 'Fail when a public object of the API has no documentation'
+    task :coverage do
+      # The registry must be empty and the files must be read again. YARD keeps a
+      # cache in .yardoc, and a run against that cache reports the state of the
+      # last run instead of the state of the code.
+      YARD::Registry.clear
+      YARD::CLI::Yardoc.run('--no-output', '--no-save', '--no-stats', '--quiet')
+
+      # The raw text of the docstring decides. `blank?` and `present?` do not
+      # work here: YARD gives every method whose name ends with a question mark
+      # an automatic `@return [Boolean]` tag, thus such a method looks
+      # documented even without a single comment line.
+      undocumented = YARD::Registry.all.reject do |object|
+        object.docstring.all.to_s.strip.present? ||
+          object.visibility != :public ||
+          object.tag(:api)&.text == 'private'
+      end
+
+      unless undocumented.empty?
+        undocumented.sort_by(&:path).each { |object| warn("undocumented: #{object.path}") }
+        abort("#{undocumented.size} public objects of the API have no documentation.")
+      end
+
+      puts 'The public API is documented.'
+    end
+  end
+rescue LoadError
+  # YARD is a development dependency. The tasks are missing without it.
+  nil
+end
+
+# The schema of the dummy application is in Git and names a Rails version. An
+# older Rails refuses a newer schema with "Unknown migration version", thus the
+# file must name the lowest supported Rails.
+#
+# This is a Rake task and not a test. The CI runs the migrations before the
+# suite, and on a newer Rails that run rewrites the file. A test would then read
+# the fresh file and not the file of the commit.
+LOWEST_SUPPORTED_RAILS_SCHEMA = '8.0'
+
+desc 'Check that the schema of the dummy application names the lowest supported Rails'
+task :check_dummy_schema do
+  path = File.expand_path('test/dummy/db/schema.rb', __dir__)
+  declared = File.read(path)[/ActiveRecord::Schema\[([\d.]+)\]/, 1]
+
+  if declared == LOWEST_SUPPORTED_RAILS_SCHEMA
+    puts "The dummy schema names Rails #{declared}."
+  else
+    abort(
+      "test/dummy/db/schema.rb names Rails #{declared.inspect}, expected " \
+      "#{LOWEST_SUPPORTED_RAILS_SCHEMA.inspect}. Running the migrations on a newer Rails " \
+      'rewrites this line. Set it back before you commit, else the matrix job of the ' \
+      'lowest Rails cannot load the schema.'
+    )
+  end
+end
+
 task default: :test

data/app/controllers/paper_trail_history/application_controller.rb

@@ -1,6 +1,84 @@
 # frozen_string_literal: true
 
 module PaperTrailHistory
-  class ApplicationController < ActionController::Base
+  # Base controller of the engine. It applies the access rules that the host
+  # application sets with PaperTrailHistory.configure.
+  class ApplicationController < PaperTrailHistory.config.parent_controller_class
+    include Pagy::Method
+
+    # The engine keeps its own layout, also when it descends from a controller
+    # of the host application that declares a different one.
+    layout 'paper_trail_history/application'
+
+    before_action :require_configured_access
+    before_action :run_authentication_callback
+
+    class << self
+      # Writes the warning about unconfigured access one time for each process.
+      def warn_about_unconfigured_access
+        return if @unconfigured_access_warned
+
+        @unconfigured_access_warned = true
+        Rails.logger.warn(
+          '[paper_trail_history] The engine runs without access control. It shows the full audit trail ' \
+          'and can overwrite records. Set config.authenticate_with or config.parent_controller in an ' \
+          'initializer before you deploy. See the README for details.'
+        )
+      end
+    end
+
+    private
+
+    # Finds the trackable model of the request, or redirects.
+    #
+    # The name of the parameter differs between the controllers, thus the caller
+    # gives the value.
+    #
+    # @param model_name [String] value of the parameter that names the model
+    # @return [TrackableModel, nil] nil after a redirect
+    def find_trackable_model_or_redirect(model_name)
+      trackable_model = TrackableModel.find(model_name)
+      return trackable_model if trackable_model
+
+      redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: model_name)
+      nil
+    end
+
+    # Reads one page of the given versions and decorates only that page.
+    #
+    # The engine passes the limit for each call instead of writing it into
+    # Pagy::OPTIONS, because Pagy::OPTIONS is global and belongs to the host
+    # application.
+    def paginate_versions(versions)
+      pagy, page_of_versions = pagy(:offset, versions, limit: PaperTrailHistory.config.page_limit)
+
+      [pagy, VersionDecorator.decorate_collection(page_of_versions)]
+    end
+
+    def require_configured_access
+      return if PaperTrailHistory.config.access_configured?
+
+      unless PaperTrailHistory.config.enforce_access_control?
+        self.class.warn_about_unconfigured_access
+        return
+      end
+
+      render plain: t('paper_trail_history.errors.access_not_configured'), status: :forbidden
+    end
+
+    def run_authentication_callback
+      callback = PaperTrailHistory.config.authenticate_with
+      return if callback.nil?
+
+      instance_exec(&callback)
+    end
+
+    def authorize_restore
+      callback = PaperTrailHistory.config.authorize_restore_with
+      return if callback.nil?
+      return if instance_exec(&callback)
+
+      redirect_back_or_to(root_path, alert: t('paper_trail_history.errors.restore_not_allowed'))
+    end
   end
 end

data/app/controllers/paper_trail_history/models_controller.rb

@@ -4,16 +4,13 @@ module PaperTrailHistory
   # Controller for managing trackable model operations and displaying version histories
   class ModelsController < ApplicationController
     def index
-      @trackable_models = TrackableModel.all_with_counts
+      @show_counts = PaperTrailHistory.config.show_version_counts
+      @trackable_models = @show_counts ? TrackableModel.all_with_counts : TrackableModel.all
     end
 
     def show
-      @trackable_model = TrackableModel.find(params[:name])
-
-      unless @trackable_model
-        redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: params[:name])
-        return
-      end
+      @trackable_model = find_trackable_model_or_redirect(params[:name])
+      return unless @trackable_model
 
       @recent_versions = VersionDecorator.decorate_collection(
         @trackable_model.recent_versions(20)
@@ -21,7 +18,7 @@ module PaperTrailHistory
     end
 
     def versions
-      @trackable_model = find_trackable_model_or_redirect
+      @trackable_model = find_trackable_model_or_redirect(params[:name])
       return unless @trackable_model
 
       load_versions_data
@@ -30,19 +27,9 @@ module PaperTrailHistory
 
     private
 
-    def find_trackable_model_or_redirect
-      trackable_model = TrackableModel.find(params[:name])
-      unless trackable_model
-        redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: params[:name])
-        return nil
-      end
-      trackable_model
-    end
-
     def load_versions_data
-      @versions = VersionService.for_model(params[:name], filter_params)
-      @versions = @versions.includes(:item)
-      @decorated_versions = VersionDecorator.decorate_collection(@versions)
+      @versions = VersionService.for_model(params[:name], filter_params).includes(:item)
+      @pagy, @decorated_versions = paginate_versions(@versions)
     end
 
     def load_filter_options

data/app/controllers/paper_trail_history/records_controller.rb

@@ -4,7 +4,7 @@ module PaperTrailHistory
   # Controller for managing individual record operations and their version histories
   class RecordsController < ApplicationController
     def show
-      @trackable_model = find_trackable_model_or_redirect
+      @trackable_model = find_trackable_model_or_redirect(params[:model_name])
       return unless @trackable_model
 
       load_record_data
@@ -12,7 +12,7 @@ module PaperTrailHistory
     end
 
     def versions
-      @trackable_model = find_trackable_model_or_redirect
+      @trackable_model = find_trackable_model_or_redirect(params[:model_name])
       return unless @trackable_model
 
       load_record_data
@@ -22,17 +22,11 @@ module PaperTrailHistory
 
     private
 
-    def find_trackable_model_or_redirect
-      trackable_model = TrackableModel.find(params[:model_name])
-      unless trackable_model
-        redirect_to models_path, alert: t('paper_trail_history.errors.model_not_found', model_name: params[:model_name])
-        return nil
-      end
-      trackable_model
-    end
-
     def load_record_data
-      @record = @trackable_model.klass.find_by(id: params[:record_id])
+      klass = @trackable_model.klass
+      # PaperTrail writes the value of the primary key into item_id. A model can
+      # use a primary key that is not called id.
+      @record = klass.find_by(klass.primary_key => params[:record_id])
       @record_id = params[:record_id]
     end
 
@@ -43,8 +37,10 @@ module PaperTrailHistory
     end
 
     def load_versions_with_filters
+      # No preload of :item here. This list shows the versions of one record and
+      # does not show the name of the item, thus a preload would only cost a query.
       @versions = VersionService.for_record(params[:model_name], params[:record_id], filter_params)
-      @decorated_versions = VersionDecorator.decorate_collection(@versions)
+      @pagy, @decorated_versions = paginate_versions(@versions)
     end
 
     def load_available_events

data/app/controllers/paper_trail_history/versions_controller.rb

@@ -3,29 +3,42 @@
 module PaperTrailHistory
   # Controller for managing version operations like viewing and restoring specific versions
   class VersionsController < ApplicationController
+    before_action :authorize_restore, only: :restore
     before_action :find_version, only: %i[show restore]
 
     def show
-      @decorated_version = VersionDecorator.decorate(@version)
       @trackable_model = TrackableModel.find(@version.item_type)
+      return redirect_to_missing_model unless @trackable_model
+
+      @decorated_version = VersionDecorator.decorate(@version)
     end
 
     def restore
-      result = VersionService.restore_version(@version.id)
+      result = VersionService.restore_version(@version)
 
       if result[:success]
-        redirect_back_or_to(version_path(@version), notice: result[:message])
+        redirect_back_or_to(version_path(@version, model_name: @version.item_type), notice: result[:message])
       else
-        redirect_back_or_to(version_path(@version),
+        redirect_back_or_to(version_path(@version, model_name: @version.item_type),
                             alert: t('paper_trail_history.errors.restore_failed', error: result[:error]))
       end
     end
 
     private
 
+    # The version keeps the name of its model as text. An application that
+    # renames or deletes a model keeps versions that point to a name which is not
+    # trackable now. The page must not fail with an error in this case.
+    def redirect_to_missing_model
+      redirect_to models_path,
+                  alert: t('paper_trail_history.errors.model_not_found', model_name: @version.item_type)
+    end
+
     def find_version
-      @version = PaperTrail::Version.find(params[:id])
-    rescue ActiveRecord::RecordNotFound
+      @version = VersionService.find_version(params[:id], params[:model_name])
+
+      return if @version
+
       redirect_to root_path, alert: t('paper_trail_history.errors.version_not_found')
     end
   end

data/app/helpers/paper_trail_history/application_helper.rb

@@ -3,5 +3,77 @@
 module PaperTrailHistory
   # Helper module providing utility methods for PaperTrailHistory views
   module ApplicationHelper
+    # Generate version path with model_name context when available
+    def version_link_path(version, options = {})
+      model_name = options[:model_name] || version.item_type
+      version_path(version.id, model_name: model_name)
+    end
+
+    # Generate restore version path with model_name context
+    def restore_version_link_path(version, options = {})
+      model_name = options[:model_name] || version.item_type
+      restore_version_path(version.id, model_name: model_name)
+    end
+
+    # Gives the nonce of the Content Security Policy, or nil.
+    #
+    # An empty nonce attribute is not useful: the browser refuses it and writes
+    # an error. The engine writes no attribute if the host application makes no
+    # nonce.
+    #
+    # @return [String, nil]
+    def engine_csp_nonce
+      content_security_policy_nonce.presence
+    end
+
+    # Makes the link tag for one of the stylesheets of the interface.
+    #
+    # The tag carries the integrity value, and a nonce when the host application
+    # uses a Content Security Policy with nonces. A policy that permits no other
+    # origin thus still works, if the host application serves the file itself.
+    #
+    # @param name [Symbol] key in the assets configuration
+    # @return [ActiveSupport::SafeBuffer]
+    def engine_stylesheet_tag(name)
+      asset = PaperTrailHistory.config.assets.fetch(name)
+
+      tag.link(rel: 'stylesheet', href: asset[:href], **asset_integrity_options(asset))
+    end
+
+    # Makes the script tag for one of the scripts of the interface.
+    #
+    # @param name [Symbol] key in the assets configuration
+    # @return [ActiveSupport::SafeBuffer]
+    def engine_javascript_tag(name)
+      asset = PaperTrailHistory.config.assets.fetch(name)
+
+      content_tag(:script, '', src: asset[:href], **asset_integrity_options(asset))
+    end
+
+    # Gives the attributes of a record for the interface. The value of an
+    # attribute that the host application filters becomes a placeholder, thus a
+    # password digest or an API token does not appear on the page.
+    #
+    # @param record [ActiveRecord::Base]
+    # @return [Array<Array(String, Object)>] pairs of name and value
+    def displayed_attributes(record)
+      record.attributes.map do |name, value|
+        next [name, t('paper_trail_history.display.filtered')] if PaperTrailHistory.config.filtered_attribute?(name)
+
+        [name, value]
+      end
+    end
+
+    private
+
+    # A file of another origin needs crossorigin together with integrity, else
+    # the browser cannot check the value. A file without an integrity value gets
+    # neither of the two attributes.
+    def asset_integrity_options(asset)
+      options = { nonce: engine_csp_nonce }
+      return options if asset[:integrity].blank?
+
+      options.merge(integrity: asset[:integrity], crossorigin: 'anonymous')
+    end
   end
 end