viewing_as 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ffb916a874b9d62394586bab4eb9416af1ec95d1b58a9202703b3d60aaffb462
+  data.tar.gz: 58a55ed4a4983bee755c07d7a24c4c534613f9dbeb41b3caaa9ba15b4d74b704
+SHA512:
+  metadata.gz: b026ed16a77e7b0269f70a2ac530071406d61c44541a703d42e8590f11cf6d8f61fe74510393b8c180eeebb7c23074107ed592d27fe4abca35120758a8d65b9d
+  data.tar.gz: 4e36304c4400f95a8d3e12e2a8572d41567c19b6fde32a2e834aa86249e9d3f79c0512acdc9cafd021ffd61e349a4026b4c2a2b0e4a7b781625be52e53bb88df

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-09-22)
+
+First release. Extracted from a production Rails 8.1 app, where it had run
+since 2026-09 with the same request specs that ship here.
+
+- Viewing sessions in a signed cookie, re-validated from the database on every request
+- Read-only by default, in two layers, with a per-session override
+- Fail-closed 409 when a write lands after the session has ended
+- Absolute server-side timeout, logged as its own event
+- Event log with owner-readable descriptions, deduped page views, append-only rows
+- Consent hook checked at start and on every request
+- Banner partial, `no-store`, Action Cable mixin
+- `rails g viewing_as:install`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# viewing_as
+
+Let an administrator see an account as its owner sees it, without being able
+to change it. Built for the Rails 8 authentication generator; works with
+anything that can answer "who is signed in".
+
+- **Read-only by default, in two layers.** Every request that is not GET or
+  HEAD is refused before the action runs, and the action itself runs inside
+  `ActiveRecord::Base.while_preventing_writes` for whatever the first layer
+  cannot see. Both are settings; a support team that needs to fix things as
+  the customer can start a writable session and get the same log.
+- **Re-validated on every request.** The cookie names a target and the admin's
+  own session; the database says whether the admin is still an admin, whether
+  that session still exists, and whether the owner still permits it. A "no"
+  from any of those ends the session on the next click, without touching
+  anybody's browser.
+- **Fails closed.** If the session expires or is revoked on a request that was
+  going to write, the response is 409 and nothing happens. Without this the
+  filter chain carries on with the admin as the acting user, and a click aimed
+  at the customer's account lands on the admin's own.
+- **Time-boxed.** An absolute server-side timeout, logged when it runs out.
+- **Logged in words the owner can read.** "Started viewing your account as you
+  see it." Refusals are logged too. Page views collapse to one row per quarter
+  hour; lifecycle rows never collapse; rows outlive the admin who made them
+  and cannot be edited through ActiveRecord.
+- **Not the Rails session.** State lives in its own signed cookie. Merely
+  loading `session[]` makes Rack emit `Set-Cookie`, which un-caches the page at
+  any CDN in front of the app. Reading a second signed cookie costs nothing.
+
+## How it compares
+
+| | viewing_as | pretender | devise_masquerade | switch_user |
+|---|---|---|---|---|
+| Read-only mode | two layers, per-session override | no | no | no |
+| Re-validated from the database each request | yes | signed-in check only | no | no |
+| Fails closed on mid-request expiry | 409 | n/a | n/a | n/a |
+| Server-side timeout | yes, logged | no | link token only | no |
+| Event log | yes, owner-readable | no | no | no |
+| Consent hook | yes, checked every request | no | no | `controller_guard` |
+| Storage | signed cookie | `session[]` | session or cache | `session[]` |
+| Auth coupling | Rails 8 generator by default; lambdas for anything else | agnostic | Devise only | Devise, Sorcery, others |
+
+pretender is fifty lines that swap `current_user`, and if that is all you need
+it is the right choice. This library is for the case where somebody's data is
+on the other side of the button.
+
+## Install
+
+```ruby
+gem "viewing_as"
+```
+
+```
+bin/rails generate viewing_as:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/viewing_as.rb`, a migration for
+`viewing_as_events`, an `ImpersonationsController`, two routes, and then
+edits three files: it includes `ViewingAs::Controller` in
+`ApplicationController` after `include Authentication`, prepends
+`ViewingAs::CurrentUser` into `Current`, and renders the banner at the top of
+the layout. Each edit is skipped if already made.
+
+Put a button somewhere an admin can reach:
+
+```erb
+<%= button_to "View as #{user.email_address}", impersonation_path(user), method: :post %>
+```
+
+The generator's `User` has no `admin` column. Add one, or tell the initializer
+how else to decide:
+
+```ruby
+ViewingAs.configure do |c|
+  c.may_impersonate = ->(user) { user.admin? }
+end
+```
+
+## Consent, and every other decision
+
+```ruby
+ViewingAs.configure do |c|
+  c.timeout = 30.minutes
+
+  # true, or a String saying why not. Logged as a refusal when a session
+  # starts; checked again on every request, so a "no" ends a running session.
+  c.may_be_viewed = lambda do |target, admin|
+    if target.admin? then "That account is an administrator."
+    elsif target.declined_review? then "That customer has withdrawn permission."
+    else true
+    end
+  end
+
+  # Read-only unless a controller says impersonate(user, read_only: false).
+  c.read_only = true
+  c.read_only_layers = %i[ policy database ]
+
+  # Keep one log: point at your own model instead of viewing_as_events. It
+  # must respond to record!(admin:, user:, kind:, request:, detail:); the
+  # kinds are the strings in ViewingAs::Kinds.
+  c.event_model = "AdminAccessEvent"
+
+  # Who is here, and what binds the cookie to their sign-in. The defaults read
+  # the generator's Current.session.
+  c.true_user = ->(controller) { Current.session&.user }
+  c.session_id = ->(controller) { Current.session&.id }
+  c.find_target = ->(id) { User.find_by(id: id) }
+  c.display = ->(user) { user.email_address }
+end
+```
+
+## In a controller
+
+```ruby
+attempt = impersonate(user)           # or impersonate(user, read_only: false)
+attempt.started?                      # true, or false with attempt.reason
+end_impersonation!                    # the way out; logs a stop row
+
+true_user                             # who is actually here; use for every permission check
+impersonated_user                     # who the request acts as, or nil
+impersonating?
+impersonation_read_only?
+impersonation_expires_at
+```
+
+`Current.user` answers with the viewed account while a session is on, which
+is what lets the rest of the app work unmodified. Anything that must know who
+is really here reads `true_user`.
+
+The stop action is the one write the read-only guards must let through. The
+generated controller skips them on `destroy` and nowhere else:
+
+```ruby
+skip_before_action :refuse_writes_while_impersonating, only: :destroy
+skip_around_action :read_only_while_impersonating, only: :destroy
+```
+
+An admin area should refuse to render while a session is on, or every
+`Current.user` on every page would be the customer, including the ones
+deciding what to render:
+
+```ruby
+before_action { redirect_to root_path, alert: "Stop viewing first." if impersonating? }
+```
+
+## Action Cable
+
+A connection identifies itself by the session's user and has nothing the
+read-only guard can wrap. Refuse it while viewing:
+
+```ruby
+class ApplicationCable::Connection < ActionCable::Connection::Base
+  include ViewingAs::Cable
+
+  def connect
+    reject_unauthorized_connection if viewing_another_account?
+    ...
+```
+
+## What the owner sees
+
+`ViewingAs::Event` rows for a user, newest first, each with `description`,
+`reviewer`, `detail` and `created_at`:
+
+```ruby
+ViewingAs::Event.where(user: current_user).newest_first
+```
+
+These rows live in the same database as everything else. They bound what the
+application permits, not what a person with a console can do. Say so wherever
+you describe the log to your users.
+
+## What it does not cover
+
+- Writes that are not ActiveRecord: a viewed GET that enqueues a job, sends
+  mail or writes to S3 still does. A spec asserting no job is enqueued during
+  a viewed GET is what keeps that true in the app this was extracted from.
+- A CDN that forwards cookies on some paths and not others will render the
+  banner only where the cookie reaches. That is also where the owner's data
+  can reach, so nothing is disclosed without the banner; what is lost is the
+  reminder while wandering the public pages.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+```
+
+The specs run against `spec/dummy`, a Rails app with the authentication
+generator's output and this library's install applied.
+
+## License
+
+MIT.

data/app/models/viewing_as/event.rb

@@ -0,0 +1,74 @@
+module ViewingAs
+  # One record of someone on the team looking at an account through a viewing
+  # session. The account owner reads their own rows, which is what makes this
+  # a control rather than a promise.
+  #
+  # These rows live in the same database as everything else, so they bound
+  # what the application permits, not what a person with a console can do.
+  # Say that out loud wherever you describe the log to your users.
+  class Event < ActiveRecord::Base
+    self.table_name = "viewing_as_events"
+
+    # Optional, because the row has to outlive the account it names. #reviewer
+    # is what views should read; the association is a convenience on top of
+    # the address, not the source of it.
+    belongs_to :admin_user, class_name: ViewingAs.config.user_class, optional: true
+    belongs_to :user, class_name: ViewingAs.config.user_class
+
+    validates :kind, inclusion: { in: Kinds::ALL }
+
+    scope :newest_first, -> { order(created_at: :desc, id: :desc) }
+
+    # A log an admin can edit is not a log. Binds ActiveRecord only.
+    def readonly?
+      persisted?
+    end
+
+    def description
+      Kinds::DESCRIPTIONS.fetch(kind) { kind.humanize }
+    end
+
+    # Who looked, as recorded at the time. Survives the account being deleted,
+    # which is the whole reason the column exists.
+    def reviewer
+      admin_email.presence ||
+        (admin_user && ViewingAs.config.display.call(admin_user)) ||
+        "a former team member"
+    end
+
+    # Writes one row, or doesn't, and never raises in the middle of a page.
+    #
+    # Returns the row, or nil when it was deduped away. Callers use it for its
+    # effect; nothing branches on the return.
+    def self.record!(admin:, user:, kind:, request: nil, detail: nil)
+      return nil if admin.nil? || user.nil?
+
+      kind = kind.to_s
+      return nil if deduped?(admin, user, kind, detail)
+
+      create!(admin_user: admin, admin_email: ViewingAs.config.display.call(admin),
+              user: user, kind: kind, detail: detail,
+              ip_address: request&.remote_ip,
+              user_agent: request&.user_agent&.to_s&.truncate(255))
+    rescue ActiveRecord::ActiveRecordError => e
+      # An audit row failing must not take down the page it was auditing. Loud
+      # in the log, silent on the screen.
+      logger.error("[ViewingAs::Event] could not record #{kind}: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # One row per admin, per account, per kind, per detail, per window. Keyed
+    # on the detail too, or ten distinct reads of one kind inside a window
+    # would write one row naming the first and say nothing about the rest.
+    #
+    # No unique index behind this: two concurrent requests can both pass and
+    # write a pair of rows, which in an append-only log is harmless.
+    def self.deduped?(admin, user, kind, detail)
+      return false if Kinds::DISCRETE.include?(kind)
+
+      where(admin_user_id: admin.id, user_id: user.id, kind: kind, detail: detail,
+            created_at: ViewingAs.config.dedupe_window.ago..).exists?
+    end
+    private_class_method :deduped?
+  end
+end

data/app/views/viewing_as/_banner.html.erb

@@ -0,0 +1,21 @@
+<%# Self-gating: render it unconditionally from the layout. Unstyled on purpose;
+    copy it into app/views/viewing_as/_banner.html.erb to change the words or
+    add classes. Pass stop_path: if your stop route is named differently. %>
+<% if impersonating? %>
+  <div class="viewing-as-banner" role="status">
+    <span class="viewing-as-banner__text">
+      You are viewing <strong><%= ViewingAs.config.display.call(impersonated_user) %></strong>
+      as <%= ViewingAs.config.display.call(true_user) %>.
+      <% if impersonation_read_only? %>
+        Nothing you do here can change their account, and they can see a record of this visit.
+      <% else %>
+        Everything you do here is done as them, and they can see a record of this visit.
+      <% end %>
+      <% if impersonation_expires_at %>
+        Ends in <%= distance_of_time_in_words(Time.current, impersonation_expires_at) %>.
+      <% end %>
+    </span>
+    <%= button_to "Stop viewing", local_assigns.fetch(:stop_path) { stop_impersonation_path },
+                  method: :delete, class: "viewing-as-banner__stop" %>
+  </div>
+<% end %>

data/lib/generators/viewing_as/install/install_generator.rb

@@ -0,0 +1,101 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ViewingAs
+  module Generators
+    # rails generate viewing_as:install
+    #
+    # Writes the initializer, the events migration and an ImpersonationsController;
+    # adds the two routes; includes the concern in ApplicationController after
+    # Authentication; prepends the Current mixin; renders the banner in the
+    # layout. Every step is idempotent and says what it skipped.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_migration, type: :boolean, default: false,
+                   desc: "Skip the viewing_as_events migration (you keep your own log)"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/viewing_as.rb"
+      end
+
+      def create_migration_file
+        return if options[:skip_migration]
+
+        migration_template "migration.rb.tt", "db/migrate/create_viewing_as_events.rb"
+      end
+
+      def create_controller
+        template "impersonations_controller.rb", "app/controllers/impersonations_controller.rb"
+      end
+
+      def add_routes
+        route <<~ROUTES
+          # Viewing an account as its owner. No id on the stop route: the cookie
+          # already knows who, which is what lets the banner offer it from any page.
+          post "impersonations/:id", to: "impersonations#create", as: :impersonation
+          delete "impersonation", to: "impersonations#destroy", as: :stop_impersonation
+        ROUTES
+      end
+
+      def include_controller_concern
+        path = "app/controllers/application_controller.rb"
+        line = "  include ViewingAs::Controller\n"
+        return say_status(:skip, "#{path} already includes ViewingAs::Controller", :yellow) if contains?(path, "ViewingAs::Controller")
+
+        if contains?(path, /^\s*include Authentication\s*$/)
+          inject_into_file path, line, after: /^\s*include Authentication\s*\n/
+        else
+          inject_into_class path, "ApplicationController", line
+        end
+      end
+
+      def prepend_current_mixin
+        path = "app/models/current.rb"
+        if File.exist?(destination(path))
+          return say_status(:skip, "#{path} already prepends ViewingAs::CurrentUser", :yellow) if contains?(path, "ViewingAs::CurrentUser")
+
+          inject_into_class path, "Current", "  prepend ViewingAs::CurrentUser\n"
+        else
+          template "current.rb", path
+        end
+      end
+
+      def render_banner
+        path = "app/views/layouts/application.html.erb"
+        return say_status(:skip, "#{path} not found; render \"viewing_as/banner\" in your layout", :yellow) unless File.exist?(destination(path))
+        return say_status(:skip, "#{path} already renders the banner", :yellow) if contains?(path, "viewing_as/banner")
+
+        inject_into_file path, "    <%= render \"viewing_as/banner\" %>\n", after: /<body[^>]*>\n/
+      end
+
+      def show_next_steps
+        say ""
+        say "Next:"
+        say "  1. Review config/initializers/viewing_as.rb: may_impersonate and may_be_viewed are the policy."
+        say "  2. bin/rails db:migrate" unless options[:skip_migration]
+        say "  3. Put a button somewhere: button_to \"View as\", impersonation_path(user), method: :post"
+        say "  4. Style .viewing-as-banner, or copy the partial to app/views/viewing_as/_banner.html.erb."
+      end
+
+      private
+
+      def users_table
+        ViewingAs.config.user_klass.table_name
+      rescue StandardError
+        "users"
+      end
+
+      def destination(path)
+        File.join(destination_root, path)
+      end
+
+      def contains?(path, needle)
+        full = destination(path)
+        File.exist?(full) && File.read(full).match?(needle.is_a?(Regexp) ? needle : Regexp.new(Regexp.escape(needle)))
+      end
+    end
+  end
+end

data/lib/generators/viewing_as/install/templates/current.rb

@@ -0,0 +1,6 @@
+class Current < ActiveSupport::CurrentAttributes
+  prepend ViewingAs::CurrentUser
+
+  attribute :session
+  delegate :user, to: :session, allow_nil: true
+end

data/lib/generators/viewing_as/install/templates/impersonations_controller.rb

@@ -0,0 +1,38 @@
+# Starting and stopping a viewing session. The read-only guards are inherited
+# from ApplicationController; #destroy is the one write they must let through,
+# because it is the way out.
+class ImpersonationsController < ApplicationController
+  # NOT require_authentication, deliberately. That redirects to sign-in, and a
+  # redirect is an answer: it tells whoever is poking at the URL that it
+  # exists and wants a session. A signed-out stranger, a signed-in customer
+  # and a made-up id all get the same 404 below.
+  allow_unauthenticated_access
+  before_action :require_impersonator
+  skip_before_action :refuse_writes_while_impersonating, only: :destroy
+  skip_around_action :read_only_while_impersonating, only: :destroy
+
+  def create
+    target = User.find(params[:id])
+    attempt = impersonate(target)
+
+    if attempt.started?
+      redirect_to root_path, notice: "Viewing as #{ViewingAs.config.display.call(target)}."
+    else
+      redirect_back_or_to root_path, alert: attempt.reason
+    end
+  end
+
+  def destroy
+    end_impersonation!
+    redirect_to root_path, notice: "Stopped viewing that account.", status: :see_other
+  end
+
+  private
+
+  def require_impersonator
+    ViewingAs.config.resume_session.call(self)
+    return if true_user && ViewingAs.config.may_impersonate.call(true_user)
+
+    raise ActiveRecord::RecordNotFound
+  end
+end

data/lib/generators/viewing_as/install/templates/initializer.rb

@@ -0,0 +1,51 @@
+# Viewing an account as its owner. The lambdas below are the policy; the
+# library is the mechanism. Every default here matches the Rails 8
+# authentication generator; change what does not match your app.
+ViewingAs.configure do |c|
+  # How long a viewing session lasts. Absolute, enforced server-side, logged
+  # when it runs out.
+  c.timeout = 30.minutes
+
+  # Who may view other accounts. The default asks the signed-in user `admin?`;
+  # the generator's User has no such column, so add one or answer some other way.
+  # c.may_impersonate = ->(user) { user.admin? }
+
+  # Whether a given account may be viewed, by whom. Return true, or a String
+  # saying why not; the String is logged as a refusal and shown to the admin.
+  # Checked again on every request, so a "no" ends a running session at once.
+  # This is where the account owner's consent belongs.
+  # c.may_be_viewed = lambda do |target, admin|
+  #   if target.admin? then "That account is an administrator."
+  #   elsif target.declined_review? then "That customer has withdrawn permission."
+  #   else true
+  #   end
+  # end
+
+  # Read-only by default: no non-GET requests, and no ActiveRecord writes,
+  # while viewing. A controller may start a writable session with
+  # impersonate(user, read_only: false); the log records which kind it was.
+  c.read_only = true
+
+  # Which read-only guards run: :policy (refuse non-GET) and :database
+  # (ActiveRecord::Base.while_preventing_writes). Drop :database only if a
+  # viewed GET genuinely has to write, and you accept what that means.
+  c.read_only_layers = %i[ policy database ]
+
+  # Where events go. The default table is viewing_as_events (see the migration).
+  # Point this at your own model if you already keep a log; it must respond to
+  # record!(admin:, user:, kind:, request:, detail:).
+  # c.event_model = "AdminAccessEvent"
+
+  # Page-view rows within this window collapse into one. Start, stop, expiry,
+  # revocation and refusal rows never do.
+  c.dedupe_window = 15.minutes
+
+  # How to name a person in the banner and the log.
+  # c.display = ->(user) { user.email_address }
+
+  # Advanced: who is signed in, and what binds the cookie to their sign-in.
+  # The defaults read the generator's Current.session.
+  # c.true_user = ->(controller) { Current.session&.user }
+  # c.session_id = ->(controller) { Current.session&.id }
+  # c.find_target = ->(id) { User.find_by(id: id) }
+end

data/lib/generators/viewing_as/install/templates/migration.rb.tt

@@ -0,0 +1,20 @@
+class CreateViewingAsEvents < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :viewing_as_events do |t|
+      # Nullified, not cascaded, when the admin's account goes: the row has to
+      # outlive the person it names. admin_email is what views should show.
+      t.references :admin_user, foreign_key: { to_table: :<%= users_table %>, on_delete: :nullify }
+      t.string :admin_email
+      t.references :user, null: false, foreign_key: { to_table: :<%= users_table %>, on_delete: :cascade }
+      t.string :kind, null: false
+      t.string :detail
+      t.string :ip_address
+      t.string :user_agent
+      t.datetime :created_at, null: false
+    end
+
+    add_index :viewing_as_events, [ :admin_user_id, :user_id, :kind, :created_at ],
+              name: "index_viewing_as_events_on_dedupe"
+    add_index :viewing_as_events, [ :user_id, :created_at ]
+  end
+end

data/lib/viewing_as/cable.rb

@@ -0,0 +1,24 @@
+module ViewingAs
+  # For ApplicationCable::Connection.
+  #
+  # A connection identifies itself by the SESSION's user and has no request,
+  # no filter chain and nothing the read-only guard can wrap. A channel opened
+  # while an admin is viewing an account would therefore run as the admin,
+  # with the admin's reach, from a page rendered as somebody else. The honest
+  # answer is to refuse the connection until the viewing session ends:
+  #
+  #   class Connection < ActionCable::Connection::Base
+  #     include ViewingAs::Cable
+  #     identified_by :current_user
+  #
+  #     def connect
+  #       reject_unauthorized_connection if viewing_another_account?
+  #       ...
+  module Cable
+    private
+
+    def viewing_another_account?
+      cookies.signed[ViewingAs.config.cookie_name].present?
+    end
+  end
+end

data/lib/viewing_as/configuration.rb

@@ -0,0 +1,131 @@
+module ViewingAs
+  # Every decision that belongs to the host application, made explicit.
+  #
+  # The defaults are the Rails 8 authentication generator's shapes: a Current
+  # with a `session` whose `user` is who is signed in, a `User` model, and an
+  # `admin?` predicate on it. A host built some other way overrides the lambdas
+  # and nothing else in the library needs to know.
+  class Configuration
+    # How long a viewing session lasts from the moment it starts. Absolute, not
+    # sliding: enforced server-side off the timestamp in the cookie, and a
+    # session that runs out is logged as expired.
+    attr_accessor :timeout
+
+    # Name of the signed cookie that carries the viewing state. It is NOT the
+    # Rails session, and that is deliberate: reading a second signed cookie
+    # costs nothing on a page that never loads the session, whereas merely
+    # loading `session[]` makes Rack emit Set-Cookie and un-caches the page at
+    # any CDN in front of the app.
+    attr_accessor :cookie_name
+
+    # ->(controller) { who is actually here }. Every permission check and every
+    # log row uses this, never the impersonated user.
+    attr_accessor :true_user
+
+    # ->(controller) { an id that changes when the true user signs out }. The
+    # cookie is bound to it, so a cookie minted under one sign-in is inert
+    # under the next.
+    attr_accessor :session_id
+
+    # ->(controller) { load the sign-in state }. Called before the true user is
+    # consulted on every request that carries the cookie, so that surfaces
+    # which skip authentication still see the banner.
+    attr_accessor :resume_session
+
+    # ->(id) { the account named in the cookie, or nil }.
+    attr_accessor :find_target
+
+    # ->(user) { true if this person may view accounts at all }.
+    attr_accessor :may_impersonate
+
+    # ->(target, admin) { true, or a String saying why not }. Consulted when a
+    # session starts (the reason is logged as a refusal) and again on every
+    # request while it lasts (a false answer ends it, logged as revoked). This
+    # is where consent lives: return a reason when the account owner has said no.
+    attr_accessor :may_be_viewed
+
+    # ->(user) { how to name this person in the banner and the log }.
+    attr_accessor :display
+
+    # The class (or its name) that records events. Must respond to
+    # record!(admin:, user:, kind:, request:, detail:). The default is the
+    # library's own table; point it at your own model to keep one log.
+    attr_accessor :event_model
+
+    # Name of the host's user class, for the default event model's associations.
+    attr_accessor :user_class
+
+    # For the default event model: page-view rows within this window collapse
+    # into one. Lifecycle rows (start, stop, expired, revoked, refused) never do.
+    attr_accessor :dedupe_window
+
+    # Whether a viewing session is read-only unless the controller says
+    # otherwise when it starts one. See #read_only_layers.
+    attr_accessor :read_only
+
+    # Which guards enforce read-only. :policy refuses every request that is not
+    # GET or HEAD. :database wraps the action in
+    # ActiveRecord::Base.while_preventing_writes for whatever the policy cannot
+    # see. Both by default; drop :database only if an impersonated GET has to
+    # write something and you accept what that means.
+    attr_accessor :read_only_layers
+
+    # Stamp Cache-Control: no-store on every response rendered while viewing,
+    # so no cache between the browser and the app can hand one person's page
+    # to the next.
+    attr_accessor :no_store
+
+    # -> { whether the cookie is marked Secure }.
+    attr_accessor :secure_cookie
+
+    def initialize
+      @timeout = 30.minutes
+      @cookie_name = :impersonation
+      @true_user = ->(_controller) { ::Current.session&.user }
+      @session_id = ->(_controller) { ::Current.session&.id }
+      @resume_session = lambda do |controller|
+        controller.send(:resume_session) if controller.respond_to?(:resume_session, true)
+      end
+      @find_target = ->(id) { ViewingAs.config.user_klass.find_by(id: id) }
+      @may_impersonate = ->(user) { user.respond_to?(:admin?) && user.admin? }
+      @may_be_viewed = lambda do |target, _admin|
+        if target.respond_to?(:admin?) && target.admin?
+          "That account is an administrator."
+        else
+          true
+        end
+      end
+      @display = ->(user) { user.try(:email_address) || user.try(:email) || user.to_s }
+      @event_model = "ViewingAs::Event"
+      @user_class = "User"
+      @dedupe_window = 15.minutes
+      @read_only = true
+      @read_only_layers = %i[ policy database ]
+      @no_store = true
+      @secure_cookie = -> { defined?(::Rails) && ::Rails.env.production? }
+    end
+
+    def event_class
+      event_model.is_a?(String) ? event_model.constantize : event_model
+    end
+
+    def user_klass
+      user_class.is_a?(String) ? user_class.constantize : user_class
+    end
+
+    def read_only_layer?(layer)
+      Array(read_only_layers).map(&:to_sym).include?(layer)
+    end
+
+    # may_be_viewed may take (target) or (target, admin). Returns nil when the
+    # account may be viewed, otherwise the reason it may not.
+    def refusal_for(target, admin)
+      answer = may_be_viewed.arity.abs >= 2 ? may_be_viewed.call(target, admin) : may_be_viewed.call(target)
+      case answer
+      when true, nil then nil
+      when String then answer
+      else "That account cannot be viewed."
+      end
+    end
+  end
+end

data/lib/viewing_as/controller.rb

@@ -0,0 +1,248 @@
+require "json"
+
+module ViewingAs
+  # The controller side. Include it AFTER the callback that loads the sign-in
+  # state, because the guards below assume it has run:
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Authentication
+  #     include ViewingAs::Controller
+  #   end
+  #
+  # Registration order, top to bottom, is load-bearing:
+  #
+  #   resume_impersonation ..... re-derives the viewing state from the cookie
+  #       and the database, on every request, before anything renders. Also
+  #       where the page-view row is logged: deliberately before the
+  #       around_action that forbids writes.
+  #   refuse_writes ............ the policy: no non-GET while viewing read-only.
+  #   read_only ................ the guarantee, for whatever the policy cannot see.
+  #   no_store ................. so no cache between here and the browser keeps
+  #       a page rendered for one named person.
+  module Controller
+    extend ActiveSupport::Concern
+
+    # What #impersonate returns.
+    Attempt = Data.define(:started, :reason) do
+      def started? = started
+    end
+
+    included do
+      before_action :resume_impersonation
+      before_action :refuse_writes_while_impersonating
+      around_action :read_only_while_impersonating
+      after_action :no_store_while_impersonating
+
+      if respond_to?(:helper_method)
+        helper_method :true_user, :impersonated_user, :impersonating?,
+                      :impersonation_expires_at, :impersonation_read_only?
+      end
+    end
+
+    private
+
+    # Who is actually here. Every permission check and every log row uses this;
+    # using the acting user for either would let a viewed request authorise
+    # itself as the account owner, or file the admin's reads under the owner's
+    # own name.
+    def true_user
+      ViewingAs.config.true_user.call(self)
+    end
+
+    # Who this request acts as, when someone is viewing; nil otherwise.
+    def impersonated_user
+      ViewingAs::Current.impersonated_user
+    end
+
+    def impersonating?
+      ViewingAs::Current.impersonating?
+    end
+
+    def impersonation_expires_at
+      ViewingAs::Current.expires_at
+    end
+
+    def impersonation_read_only?
+      impersonating? && ViewingAs::Current.read_only == true
+    end
+
+    # Starts viewing `target`, or refuses and says why. Both outcomes are
+    # logged. Returns an Attempt: check #started? and read #reason.
+    #
+    # read_only: nil takes the configured default. Pass false to start a
+    # session that may write; the choice is sealed into the signed cookie, so
+    # it cannot be changed from the browser once made, and recorded on the
+    # start row so the log says which kind of session it was.
+    def impersonate(target, read_only: nil)
+      admin = true_user
+
+      unless admin && ViewingAs.config.may_impersonate.call(admin)
+        return refuse_impersonation(admin, target, "You are not permitted to view other accounts.")
+      end
+      return refuse_impersonation(admin, target, "You cannot view your own account this way.") if target == admin
+      if (reason = ViewingAs.config.refusal_for(target, admin))
+        return refuse_impersonation(admin, target, reason)
+      end
+
+      begin_impersonation!(target, read_only: read_only)
+      record_viewing_event(admin, target, Kinds::START,
+                           detail: (impersonation_read_only? ? nil : "writable"))
+      Attempt.new(started: true, reason: nil)
+    end
+
+    # Ends the current viewing session, logging `kind`. Safe to call when
+    # nothing is being viewed.
+    def end_impersonation!(kind = Kinds::STOP, subject = nil)
+      subject ||= ViewingAs.config.find_target.call(impersonation_payload&.dig("user_id"))
+      cookies.delete(ViewingAs.config.cookie_name)
+      ViewingAs::Current.impersonated_user = nil
+      ViewingAs::Current.expires_at = nil
+      ViewingAs::Current.read_only = nil
+
+      record_viewing_event(true_user, subject, kind)
+      nil
+    end
+
+    # Mints the cookie and sets the state, with no checks and no log row.
+    # #impersonate is the front door; this is here for hosts that have already
+    # decided.
+    def begin_impersonation!(target, read_only: nil)
+      read_only = ViewingAs.config.read_only if read_only.nil?
+      started_at = Time.current
+
+      cookies.signed[ViewingAs.config.cookie_name] = {
+        value: { admin_session_id: ViewingAs.config.session_id.call(self),
+                 user_id: target.id,
+                 started_at: started_at.to_i,
+                 read_only: read_only }.to_json,
+        httponly: true,
+        same_site: :lax,
+        secure: ViewingAs.config.secure_cookie.call
+        # Deliberately NO expires. The timeout is enforced server-side off
+        # started_at, and a cookie carrying the same lifetime would simply
+        # vanish from the browser first, so the expiry would never be seen here
+        # and never written to the log, leaving the account owner a session
+        # that started and apparently never ended.
+      }
+
+      ViewingAs::Current.impersonated_user = target
+      ViewingAs::Current.expires_at = started_at + ViewingAs.config.timeout
+      ViewingAs::Current.read_only = read_only
+    end
+
+    # Re-derived from scratch on every request rather than trusted from the
+    # cookie we minted. That is the whole design: consent withdrawn, an admin
+    # flag revoked, an account closed and a sign-out elsewhere all take effect
+    # on the very next click, without reaching into anybody's browser.
+    def resume_impersonation
+      payload = impersonation_payload
+      return if payload.nil?
+
+      ViewingAs.config.resume_session.call(self)
+      admin = true_user
+      target = ViewingAs.config.find_target.call(payload["user_id"])
+      started_at = payload["started_at"].to_i
+
+      if started_at < ViewingAs.config.timeout.ago.to_i
+        return finish_impersonation(Kinds::EXPIRED, target)
+      end
+
+      unless admin && ViewingAs.config.may_impersonate.call(admin) &&
+             ViewingAs.config.session_id.call(self) == payload["admin_session_id"]
+        return finish_impersonation(Kinds::REVOKED, target)
+      end
+
+      unless target && target != admin && ViewingAs.config.refusal_for(target, admin).nil?
+        return finish_impersonation(Kinds::REVOKED, target)
+      end
+
+      ViewingAs::Current.impersonated_user = target
+      ViewingAs::Current.expires_at = at(started_at) + ViewingAs.config.timeout
+      ViewingAs::Current.read_only = payload.key?("read_only") ? payload["read_only"] : ViewingAs.config.read_only
+
+      record_viewing_event(admin, target, Kinds::READ)
+    end
+
+    # Ends a session that has stopped being valid, and refuses the request if
+    # it was going to write.
+    #
+    # The refusal is the whole point. Without it the filter chain simply
+    # carries on: nothing is being viewed any more, so the write guard waves
+    # the request through, and the acting user has silently become the ADMIN.
+    # A click aimed at somebody else's account would land on the admin's own.
+    # The only honest answer is not to do it to theirs. This holds in writable
+    # sessions too; it is about whose account the click lands on, not about
+    # whether writes were allowed.
+    #
+    # Nobody signed in means nobody's account to land on: a sign-in POST made
+    # while holding a dead cookie is the visitor's own, and goes through.
+    def finish_impersonation(kind, subject)
+      end_impersonation!(kind, subject)
+      return if request.env["REQUEST_METHOD"].in?(%w[ GET HEAD ])
+      return if true_user.nil?
+
+      render plain: "That session ended before this went through. Nothing was changed.",
+             status: :conflict
+    end
+
+    # The policy: reads only.
+    #
+    # Read straight off the Rack env, the same method the router dispatched
+    # on. Rack::MethodOverride resolves _method and X-Http-Method-Override
+    # before either runs, so there is no spelling of a request that routes to
+    # a write action while presenting here as a GET.
+    def refuse_writes_while_impersonating
+      return unless impersonation_read_only? && ViewingAs.config.read_only_layer?(:policy)
+      return if request.env["REQUEST_METHOD"].in?(%w[ GET HEAD ])
+
+      render plain: "Read-only while viewing another account.", status: :forbidden
+    end
+
+    # The guarantee, for everything the policy above cannot see: an
+    # update_column in a helper, a counter cache, a touch-on-read added later.
+    # Reaching this is a bug rather than a user action, which is why it logs
+    # at error.
+    #
+    # Covers ActiveRecord only. A GET that enqueued a job, sent mail or wrote
+    # to S3 would still fire; a spec asserting no job is enqueued during a
+    # viewed GET is what keeps that true.
+    def read_only_while_impersonating
+      return yield unless impersonation_read_only? && ViewingAs.config.read_only_layer?(:database)
+
+      ActiveRecord::Base.while_preventing_writes { yield }
+    rescue ActiveRecord::ReadOnlyError => e
+      logger.error("[ViewingAs] blocked a write: #{e.message}") if respond_to?(:logger) && logger
+      render plain: "Read-only while viewing another account.", status: :forbidden
+    end
+
+    # "No Cache-Control" is not "no caching": a CDN answers it with its default
+    # TTL and would happily cache one person's account page for the next
+    # visitor. Say it.
+    def no_store_while_impersonating
+      response.headers["Cache-Control"] = "no-store" if impersonating? && ViewingAs.config.no_store
+    end
+
+    def impersonation_payload
+      raw = cookies.signed[ViewingAs.config.cookie_name]
+      raw.blank? ? nil : JSON.parse(raw)
+    rescue JSON::ParserError
+      # A signed cookie that survived verification but is not the JSON we
+      # wrote: ours, from an older shape. Treat as absent rather than 500ing.
+      nil
+    end
+
+    def refuse_impersonation(admin, target, reason)
+      record_viewing_event(admin, target, Kinds::REFUSED, detail: reason)
+      Attempt.new(started: false, reason: reason)
+    end
+
+    def record_viewing_event(admin, user, kind, detail: nil)
+      ViewingAs.config.event_class.record!(admin: admin, user: user, kind: kind,
+                                           request: request, detail: detail)
+    end
+
+    def at(epoch)
+      Time.zone ? Time.zone.at(epoch) : Time.at(epoch)
+    end
+  end
+end

data/lib/viewing_as/current.rb

@@ -0,0 +1,16 @@
+module ViewingAs
+  # The viewing state for the current request. Reset with every other
+  # CurrentAttributes at the end of the request.
+  #
+  # Kept separate from the host's Current so the library never has to know
+  # what that class is called or what else it holds. ViewingAs::CurrentUser is
+  # the bridge that makes the host's Current.user answer with the viewed
+  # account.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :impersonated_user, :expires_at, :read_only
+
+    def impersonating?
+      impersonated_user.present?
+    end
+  end
+end

data/lib/viewing_as/current_user.rb

@@ -0,0 +1,49 @@
+module ViewingAs
+  # Prepend into the host's Current so that Current.user is the viewed account
+  # while a session is on, and the signed-in user otherwise:
+  #
+  #   class Current < ActiveSupport::CurrentAttributes
+  #     prepend ViewingAs::CurrentUser
+  #     attribute :session
+  #     delegate :user, to: :session, allow_nil: true
+  #   end
+  #
+  # Prepend, not include, so it wins over a `delegate :user` or a hand-written
+  # `user` already on the class; `super` then reaches whichever the host had.
+  # With no such method it falls back to `session&.user`, the generator's shape.
+  #
+  # This is what lets every controller, model and job that reads Current.user
+  # work unmodified while an admin is viewing an account. Anything that must
+  # know who is really here reads Current.session.user, or the controller's
+  # true_user.
+  module CurrentUser
+    def self.prepended(base)
+      base.singleton_class.delegate :impersonated_user, :impersonation_expires_at,
+                                    :impersonation_read_only, :impersonating?, to: :instance
+    end
+
+    def self.included(base)
+      prepended(base)
+    end
+
+    def user
+      ViewingAs::Current.impersonated_user || (defined?(super) ? super : session&.user)
+    end
+
+    def impersonated_user
+      ViewingAs::Current.impersonated_user
+    end
+
+    def impersonation_expires_at
+      ViewingAs::Current.expires_at
+    end
+
+    def impersonation_read_only
+      ViewingAs::Current.read_only
+    end
+
+    def impersonating?
+      ViewingAs::Current.impersonating?
+    end
+  end
+end

data/lib/viewing_as/engine.rb

@@ -0,0 +1,8 @@
+module ViewingAs
+  # Autoloads app/models/viewing_as/event.rb and serves the banner partial from
+  # app/views/viewing_as/. No routes: the host owns the two it needs, which the
+  # install generator writes.
+  class Engine < ::Rails::Engine
+    engine_name "viewing_as"
+  end
+end

data/lib/viewing_as/kinds.rb

@@ -0,0 +1,33 @@
+module ViewingAs
+  # The event kinds, as strings, so a host that keeps its own log can store the
+  # same values without loading the library's model.
+  module Kinds
+    # Browsed the site as them. Deduped per window by the default event model:
+    # the question a log answers is "did someone look, and when", not "how many
+    # requests did they issue".
+    READ = "impersonated_read".freeze
+
+    # Lifecycle. Discrete facts, never deduped: two sessions an hour apart are
+    # two rows.
+    START = "impersonation_start".freeze
+    STOP = "impersonation_stop".freeze
+    EXPIRED = "impersonation_expired".freeze
+    REVOKED = "impersonation_revoked".freeze
+    REFUSED = "impersonation_refused".freeze
+
+    ALL = [ READ, START, STOP, EXPIRED, REVOKED, REFUSED ].freeze
+    DISCRETE = [ START, STOP, EXPIRED, REVOKED, REFUSED ].freeze
+
+    # Phrasing for the account owner's own view of the log. Plain on purpose:
+    # the person reading it did not build this and should not have to guess
+    # what "impersonated_read" was supposed to mean.
+    DESCRIPTIONS = {
+      READ => "Viewed your pages as you see them",
+      START => "Started viewing your account as you see it",
+      STOP => "Stopped viewing your account",
+      EXPIRED => "Stopped viewing your account (time limit reached)",
+      REVOKED => "Stopped viewing your account (permission ended)",
+      REFUSED => "Tried to view your account and was refused"
+    }.freeze
+  end
+end

data/lib/viewing_as/version.rb

@@ -0,0 +1,3 @@
+module ViewingAs
+  VERSION = "0.1.0".freeze
+end

data/lib/viewing_as.rb

@@ -0,0 +1,35 @@
+require "active_support"
+require "active_support/core_ext/numeric/time"
+require "active_support/current_attributes"
+
+require "viewing_as/version"
+require "viewing_as/configuration"
+require "viewing_as/kinds"
+require "viewing_as/current"
+require "viewing_as/current_user"
+require "viewing_as/controller"
+require "viewing_as/cable"
+require "viewing_as/engine" if defined?(Rails::Engine)
+
+# Viewing an account as its owner, without being able to change it.
+#
+# The whole library is a controller concern (ViewingAs::Controller), a mixin for
+# the host's Current (ViewingAs::CurrentUser), an event model (ViewingAs::Event)
+# and a configuration object holding every decision that belongs to the host
+# application. See README.md.
+module ViewingAs
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # For tests. Throws away every setting, including the host's.
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,124 @@
+--- !ruby/object:Gem::Specification
+name: viewing_as
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ed
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: |
+  Let an administrator view an account as its owner. Read-only by default (two
+  layers: no non-GET requests, and ActiveRecord writes refused), re-validated
+  from the database on every request so revoked consent bites on the next click,
+  time-boxed server-side, and logged in words the account owner can read.
+  Stores its state in a signed cookie rather than the Rails session, so an
+  edge-cached site stays cached. Built for the Rails 8 authentication
+  generator; works with anything that can answer "who is signed in".
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/models/viewing_as/event.rb
+- app/views/viewing_as/_banner.html.erb
+- lib/generators/viewing_as/install/install_generator.rb
+- lib/generators/viewing_as/install/templates/current.rb
+- lib/generators/viewing_as/install/templates/impersonations_controller.rb
+- lib/generators/viewing_as/install/templates/initializer.rb
+- lib/generators/viewing_as/install/templates/migration.rb.tt
+- lib/viewing_as.rb
+- lib/viewing_as/cable.rb
+- lib/viewing_as/configuration.rb
+- lib/viewing_as/controller.rb
+- lib/viewing_as/current.rb
+- lib/viewing_as/current_user.rb
+- lib/viewing_as/engine.rb
+- lib/viewing_as/kinds.rb
+- lib/viewing_as/version.rb
+homepage: https://github.com/delistmydata/viewing_as
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/delistmydata/viewing_as
+  changelog_uri: https://github.com/delistmydata/viewing_as/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/delistmydata/viewing_as/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: 'Impersonation for the Rails 8 authentication generator: read-only by default,
+  consented, time-boxed, logged'
+test_files: []