studio-engine 0.29.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db4fb7663508ced21fce80ca29ec063c300c2826e0dadc511c266219303e449d
-  data.tar.gz: b7e7c5cb133164b6d2a0521d4f08291540a78b4fb01a0be3b840f5413e35d8bb
+  metadata.gz: c36ecfe3e213e5621f205743728461c24d02912ed7e7bbf5109e0c15afd3225e
+  data.tar.gz: d92755cdb2ed3f7b8dca941bb514e2c725314056afbc83ee7fb190a4cc4a993c
 SHA512:
-  metadata.gz: 328965e3979861ddc61b3c312a665b42b4e17d4d35a45851c3c76e9c538904e8096ba20725aa81fd45ba3e0509e8cf1fa764bbac70483a26afb5d8273bb43341
-  data.tar.gz: c3323dfb24072f240935a1c3300dcf694d9c5ba22097fe2c1dc27ed04d0ee68cfb18df95844fe182e71622ccc6ba151dcb8ef3c5cc3488b5ac9959535e16c0c3
+  metadata.gz: 17c9f349695792402a9cbcb245159ebcba107b355edcdc9c5ae3b3d89d23303d0bd3a4bd96846d1d23c23417fbff47a0f73e0db887bd8880faeb4687e7e48c12
+  data.tar.gz: c65f117c47ced22be63a3747f0cd2b283f00a80c40802947a1003ada976749242ebd8340a511d89c9806d9449c6a3525eb1cbebb5fdd47d37cf334465d2e2644

data/CHANGELOG.md

@@ -2,6 +2,260 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.31.0 — 2026-08-08
+
+**One magic-link token format, one door, and a click that stops breaking your
+session.** Two operator-reported faults, one root: the engine shipped two
+magic-link stores side by side, and the legacy one could not support the
+behavior the other needed.
+
+The links themselves were the visible half — a `:signed` app mailed a
+~350-character `MessageVerifier` blob at `/magic_link/<token>`, wrapping four
+lines of an email. The invisible half was worse: **clicking a link a second time
+dumped a signed-in visitor on the login page.** Their cookie survived, but the
+destination said otherwise, and the destination is what people believe. Every
+dead token — used, expired, or unrecognized — funnelled into the same
+`redirect_to login_path, alert:` no matter who was holding a session.
+
+Fixing the second required retiring the first. An EXPIRED `MessageVerifier`
+token cannot be decoded, so a `:signed` app could not tell whose dead link it
+was holding — and "is this the visitor's own link?" is the question the whole
+new behavior turns on. A `Studio::Link` row keeps the email past expiry.
+
+### Added
+
+- **`Studio::LinkResolution`** — the click decision table as one pure,
+  dependency-free module (`lib/studio/link_resolution.rb`), so every cell is
+  unit-testable without a controller or a database. Three inputs (did this
+  caller burn the link, whose email it carries, who is signed in) resolve to one
+  of three actions:
+
+  |                  | nobody signed in | the link's own user | somebody else    |
+  |------------------|------------------|---------------------|------------------|
+  | **live** (burned)| `:authenticate`  | `:continue`         | `:authenticate`  |
+  | **used/expired** | `:dead` → login  | `:dead` → return_to | `:dead` → home   |
+  | **unknown token**| `:dead` → login  | —                   | `:dead` → home   |
+
+  The invariant running through it: **a dead link never touches the session.**
+- **`:continue`** — a second click on your own still-live link burns the token
+  (so a forwarded email stays unusable) and then does nothing else. It
+  deliberately does NOT re-authenticate: a host that rotates the session on
+  sign-in would otherwise charge a re-click every scrap of session state the
+  visitor had built up. From their side it is indistinguishable from following a
+  plain link, which is the point.
+- **Dead-link notices name the address and the reason** ("That sign-in link for
+  x@y.com has expired.") and, when a session is open, say so plainly ("You are
+  still signed in as a@b.com") instead of implying a logout that never happened.
+- **`Studio::Link#burn`** — the non-raising sibling of `#consume!`, returning
+  whether THIS caller won the atomic single-use race, plus `#dead_status`
+  (`:used` / `:expired`) for the message. Winning the burn IS the proof the link
+  was live; a prior `live?` read is not.
+- **`Studio::Link::MissingTable`** — a named error, pointing at the migration to
+  copy, in place of a bare `PG::UndefinedTable`. Every consumer pins the engine
+  `~> 0.x`, which admits any release below 1.0, so an app that never installed
+  the table picks up the row store on its next `bundle update` with nobody
+  having adopted anything deliberately. Its boot stays clean (nothing touches
+  the table until someone signs in), so without this the failure lands as an
+  unreadable adapter error on a real person's sign-in. Guarded by
+  `table_exists?`, not a message match, so it holds on any adapter and never
+  swallows an unrelated statement failure.
+- **`Studio::LinkToken::TOKEN_LENGTH` / `TOKEN_LENGTH_BOUNDS` / `TOKEN_FORMAT`** —
+  the house standard, now asserted rather than described: every token is exactly
+  16 URL-safe characters, inside a 10-20 character bound.
+- **`Studio::LinkConsumption`** gains the whole flow (`preview_magic_link` for
+  the inert GET, `consume_magic_link` for the burning POST) plus overridable
+  hooks: `link_continue`, `link_dead`, `link_login_path`, `link_home_path`.
+  Apps customize by overriding a hook, never by re-deciding.
+- **Two new suites**: `test/lib/studio/link_resolution_test.rb` (the table, cell
+  by cell, with the dead-link invariant swept across all nine cells) and
+  `test/integration/magic_link_flow_test.rb` (the same flow through a real HTTP
+  round trip against a real database — token burn, session cookie, scanner
+  prefetch, account switch, open-redirect refusal, and the burn race).
+
+### Changed
+
+- **`Studio.magic_link_store` now reads `:database` and nothing else.** Assigning
+  `:signed` **raises at boot** with the migration to install, rather than
+  silently downgrading — an app that booted anyway would mint rows against a
+  table it never migrated and 500 on a real person's sign-in.
+- **`Studio.magic_link_via_l_route?`** follows `draw_link_routes` alone.
+- **`RegistrationsController`** mints through `Studio::MagicLinkIssuing` like
+  every other issuer, instead of calling the store directly.
+
+### Removed
+
+- **`MagicLink`** (`app/services/magic_link.rb`), the stateless MessageVerifier
+  service, and its jti-in-Rails.cache replay guard.
+- **`GET`/`POST /magic_link/:token`** and `MagicLinksController#confirm` /
+  `#consume`. `POST /magic_link` (request a link) stays. The token-bearing door
+  is `/l/<token>`, and only that.
+- **`app/views/magic_links/confirm.html.erb`** — the `/l` interstitial
+  (`studio/links/confirm`) renders the same shared body.
+- **`Studio.magic_link_token_name`** is vestigial: the accessor remains so an
+  un-updated initializer still boots, but nothing reads it. Delete the line.
+
+### Consumer migration (required)
+
+**Until step 2 lands, the app's magic-link sign-in is broken** — no
+`studio_links` table means the first mint raises `Studio::Link::MissingTable`.
+Do these two in this order; they do not commute.
+
+1. Delete `config.magic_link_store` and `config.magic_link_token_name` from
+   `config/initializers/studio.rb`. **First**, because a leftover `= :signed`
+   raises while the initializer loads — and `Studio.configure` yields during
+   boot, so no rake task (including the migration install below) can run until
+   the line is gone.
+2. Install the `studio_links` table with `bin/rails
+   studio_engine:install:migrations && bin/rails db:migrate` — install ALL of
+   them, per `docs/NEW_APP_SETUP.md` § 5. Do **not** hand-copy the migration:
+   the task installs it as `<timestamp>_create_studio_links.studio_engine.rb`, a
+   hand copy keeps its own name, and both declare `class CreateStudioLinks`, so
+   `db:migrate` dies on `ActiveRecord::DuplicateMigrationNameError`.
+3. Replace any `MagicLink.generate` / `MagicLink.consume` call (including in
+   test helpers) with `Studio::Link.create_magic_link` / `Studio::Link#burn`.
+4. An app overriding the link controllers gets the new behavior by calling
+   `consume_magic_link` / `preview_magic_link` and overriding hooks. In
+   particular, move any `reset_session` into `sign_in_existing` only — the
+   `:continue` path must not reach it.
+## 0.30.1 — 2026-08-08
+
+**`NEW_APP_SETUP.md` § 5 gave a command that does not exist.** 0.30.0 documented
+the engine migration install as `bin/rails studio:install:migrations`; the real
+task is **`studio_engine:install:migrations`**, and the copied files land with a
+`.studio_engine.rb` suffix, not `.studio.rb`. The wrong spelling was inferred
+from a consumer file that had been hand-copied rather than generated, and it
+fails loudly (`Unrecognized command`) for anyone who follows the guide.
+
+**And one of the copied migrations could fail the whole run.** The task copies
+FOUR *reference* migrations, and `allow_null_image_cache_owner` runs
+`change_column_null :image_caches` — which raised on any app without that table,
+taking the entire `db:migrate` down with it. moms-app hit exactly that.
+
+The obvious answer — "review what was copied and delete what doesn't apply" — is
+wrong, and this release does NOT tell you to do it. `install:migrations` builds
+its skip-list from the files **present**, so a deleted copy comes back with a
+fresh timestamp on your next upgrade and fails again. The guard therefore lives
+in the migration, and § 5 now says the simple thing: **install all of them.**
+
+### Fixed
+
+- **`allow_null_image_cache_owner` no longer fails `db:migrate` on an app without
+  an `image_caches` table.** It ALTERS an app-owned table the engine cannot assume
+  exists, and unguarded it raised and took the whole migration run down with it.
+  It now no-ops when the table is absent, and still relaxes the owner columns when
+  it is present — both halves pinned by
+  `test/integration/image_cache_migration_guard_test.rb`.
+
+  Deleting the copied migration was never a workaround: `install:migrations`
+  builds its skip-list from the files **present**, so a deleted copy is re-copied
+  with a fresh timestamp on the next upgrade and fails again. Verified by
+  re-running the task against a real consumer.
+- `NEW_APP_SETUP.md` § 5: correct task name, correct file suffix, and — now that
+  the migration guards itself — the simple instruction to install ALL of them and
+  re-run after each upgrade.
+- `EMAIL_TRANSPORT.md`: was pointing at `railties:install:migrations`, which
+  copies the migrations of EVERY railtie in the bundle. Scoped to `studio_engine:`.
+
+## 0.30.0 — 2026-08-08
+
+**The hub's link sidebar becomes the engine's out-of-the-box navigation.** New
+apps get a default navigation surface without forking the navbar: declare
+`Studio.sidebar_sections` (a static Array or a callable receiving the view
+context; sections flagged `admin: true` show to admins only) and the engine
+navbar mounts a trigger in its desktop icon rail and mobile sub-navbar, then
+renders the slide-out link panels after the header. The family ships as
+`components/_link_sidebar` (dual desktop/mobile panels + the engine-owned
+Alpine `sidebars` store bridge, Turbo- and bfcache-safe), the generic
+`components/_sidebar_panel` shell, and `components/_link_sidebar_trigger` —
+all lifted from the mcritchie-studio hub. `engine.css` gains the
+`studio-link-sidebar-layer` stacking utility and the Alpine `[x-cloak]`
+pre-init rule. **Upgrade-safe by default:** `sidebar_sections` defaults to
+`[]`, which renders nothing — existing consumers see zero change until they
+opt in (pinned by `test/integration/sidebar_navbar_render_test.rb`). The
+`html { overflow-x: clip }` slide guard ships inside the sidebar partial, not
+globally. When the viewer's resolved sections carry an `admin: true` entry,
+the sidebar replaces the engine admin dropdown (both use the cog glyph — one
+gear, not two); public-only sections keep the dropdown. Resolution rules live
+in `lib/studio/sidebar_sections.rb` (pure Ruby, unit-tested); docs in
+`NEW_APP_SETUP.md` §4/§13 and `NAVBAR_SETUP.md`.
+
+**Off-chain apps lose the user nav's dead space.** The default second row
+(wallet address + level progress bar) renders only when it has something to
+show — a wallet, a server level, or the `show_logout_link` link. A plain
+app's signed-in nav collapses to one line instead of an empty progress strip.
+The engine navbar's fixed-width `.user-nav-col` (reserved to seat a balance)
+likewise applies only when `balance_html` is passed; without one the column
+becomes `.user-nav-fit` (shrink-to-fit, `max-width` capped for username
+truncation). turf-monster's dense nav is untouched: its users carry wallet +
+level, and it ships its own navbar. Pinned by
+`test/integration/user_nav_collapse_render_test.rb` and the user_nav view
+tests.
+
+**The dev/QA environment banner is now an engine standard a host adopts with ONE
+render call, and it carries the Local Inbox link.** Every app hand-rolled its own
+yellow "&lt;Env&gt; Environment" strip — this gem's own `NEW_APP_SETUP.md` § 9 shipped
+the `<div>` to copy — so no two apps agreed on when it showed or what it said, and
+none of them linked `/_studio/local_emails`. The engine already had the pieces
+(`studio/banners/_environment` and friends); it just could not decide *whether* to
+render, so no host could use it. It can now:
+
+```erb
+<%= render "studio/banners/environment" %>
+```
+
+No `unless Rails.env.production?` around it, no host `show_environment_banner?`,
+no forked buttons. The partial owns all three decisions — whether it appears
+(everywhere except real production; a QA app is Rails-production but a review
+target, so `QA_ENV=true` re-opens it), what it says (`"QA Environment ·
+Non-production"` on QA), and whether the inbox is linkable.
+
+**The inbox link tells the truth.** `Studio.local_inbox_reachable?` consults the
+SAME gate `Studio::LocalEmailsController` enforces, so the banner can never
+advertise a page that answers 404. Where the viewer resolves (a developer desk)
+you get a link; where it does not (QA — Rails-production, remote requests) the
+button degrades to an inert `role="status"` chip that still reports the connector
+and whether mail is sending or captured. This generalizes the degradation
+turf-monster had already built for itself.
+
+Purely additive. `Studio.local_tool_enabled?` and `Studio.local_email_capture?`
+are **unchanged** — their production hard-close still stands, which is also why
+`LOCAL_EMAIL_CAPTURE=1` on a QA dyno does nothing and QA still sends real mail.
+
+### Added
+
+- **`studio/banners/environment` self-gates** and accepts `preview:` (suppress
+  inside a navbar-preview render — a duplicate `vt-pinned-header` silently kills
+  view transitions), `extra:` (message segments), `devnet:`, and
+  `environment_label:`.
+- **`Studio::EnvironmentBanner`** — the show/label rules as dependency-free Ruby,
+  unit-tested directly so the suite exercises the shipped code, not a copy.
+- **`Studio.qa_environment?` / `.show_environment_banner?` /
+  `.environment_banner_message` / `.local_inbox_reachable?` / `.rails_env_name`.**
+  `qa_environment?` reads the existing `QA_ENV` the release conductor already sets
+  on every QA app — no new variable.
+- **`studio/banners/button` gained `as: :status`** — the same chrome, inert, for a
+  fact we can report but not navigate to.
+
+### Fixed
+
+- **`studio/banners/button` dropped every attribute on a block render.**
+  `tag.span(hash) { }` reads the hash as CONTENT, so the options never reached the
+  tag. Splatted as keywords now. Latent until `as: :status` became the first block
+  path to use it.
+
+### Docs
+
+- **`NEW_APP_SETUP.md` § 9 no longer ships a hand-rolled banner to copy** — it
+  renders the shared partial, and documents the QA/email reality.
+- **`NEW_APP_SETUP.md` § 5 now installs the engine migrations FIRST**
+  (~~`bin/rails studio:install:migrations`~~ — **erratum, 0.30.1:** that command
+  does not exist; the correct task is `studio_engine:install:migrations`).
+  Omitting them is silent:
+  `Studio::Email.deliver` records mail only when `studio_email_deliveries` exists
+  and otherwise falls back to a plain `deliver_later`, so the app drops every
+  captured email and shows an empty inbox. Exactly the mcritchie-industries bug,
+  fixed 2026-08-08.
+
 ## 0.29.1 — 2026-07-29
 
 **`Studio::Board::Rankable#reposition!` is now atomic — a mid-loop failure can no

data/README.md

@@ -2,7 +2,7 @@
 
 Shared Rails engine for McRitchie apps. Provides authentication, error handling, dynamic theming, and common concerns used by [McRitchie Studio](https://app.mcritchie.studio) and [Turf Monster](https://app.turfmonster.media).
 
-> **Part of the McRitchie ecosystem** — see [`ECOSYSTEM.md`](https://github.com/amcritchie/mcritchie-studio/blob/main/docs/ECOSYSTEM.md) for the 5-repo map; [`house-burn-down.md`](https://github.com/amcritchie/mcritchie-studio/blob/main/docs/agents/system/house-burn-down.md) for fresh-Mac recovery.
+> **Part of the McRitchie ecosystem** — see [`ECOSYSTEM.md`](https://github.com/McRitchie-Studio/mcritchie-studio/blob/main/docs/ECOSYSTEM.md) for the 5-repo map; [`house-burn-down.md`](https://github.com/McRitchie-Studio/mcritchie-studio/blob/main/docs/agents/system/house-burn-down.md) for fresh-Mac recovery.
 
 ## Installation
 
@@ -36,7 +36,6 @@ Studio.configure do |config|
   config.welcome_message = ->(user) { "Welcome, #{user.display_name}!" }
   config.auth_methods = %i[magic_link google]
   config.registration_params = [:name, :email]
-  config.magic_link_token_name = "magic_link_my_app_v1"
   config.mailer_from = Studio.mailer_from_for_transport(
     ses_from: "My App <team@example.com>"
   )
@@ -76,7 +75,9 @@ Rails.application.routes.draw do
 end
 ```
 
-This draws the enabled auth routes (`/login`, `/signup`, `/logout`, magic-link request/confirm/consume routes, Solana routes), OAuth callbacks, optional SSO routes, `/error_logs`, and `/admin/theme`. Magic-link emails point at the inert GET confirmation route; the single-use token is consumed only by the CSRF-protected POST to `magic_link_consume_path`.
+This draws the enabled auth routes (`/login`, `/signup`, `/logout`, `POST /magic_link` to request a link, `GET`/`POST /l/:token` for the link itself, Solana routes), OAuth callbacks, optional SSO routes, `/error_logs`, and `/admin/theme`. Magic-link emails point at the inert `GET /l/:token` confirmation page; the single-use token is burned only by the CSRF-protected `POST` to `link_consume_path`.
+
+**Magic links need the `studio_links` table.** Install it with `bin/rails studio_engine:install:migrations && bin/rails db:migrate` (install all of them) before enabling `:magic_link` — never by hand-copying the migration, which collides with the task's own copy on `class CreateStudioLinks`. Without the table, the first sign-in raises `Studio::Link::MissingTable`.
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
 
@@ -280,4 +281,4 @@ For short local experiments, temporarily point a consumer Gemfile at `path: "../
 Use the docs in [`docs/`](./docs) for engine setup, release, email transport,
 and host-app contracts. Current cross-repo setup, ports, credentials, and
 workflow guidance live in McRitchie Studio's
-[`docs/agents/`](https://github.com/amcritchie/mcritchie-studio/tree/main/docs/agents).
+[`docs/agents/`](https://github.com/McRitchie-Studio/mcritchie-studio/tree/main/docs/agents).

data/app/assets/tailwind/studio_engine/engine.css

@@ -181,6 +181,24 @@
   @apply px-8 py-3 text-base rounded-xl shadow-sm;
 }
 
+/* -- Link sidebar (out-of-the-box navigation) ------------------------------
+   Paired with components/_link_sidebar + _link_sidebar_trigger and the
+   Studio.sidebar_sections config. The layer sits above the sticky header
+   (z-50) and the modal host. Inert without the panel in the DOM, so apps
+   that declare no sections are unaffected. */
+
+@utility studio-link-sidebar-layer {
+  z-index: 10000;
+}
+
+/* Alpine's pre-init cloak. Engine partials (sidebar panels, dropdowns, the
+   modal host) mark themselves x-cloak so they stay hidden until Alpine boots
+   and x-show takes over. Engine-owned so every consumer gets the rule without
+   carrying the one-liner app-side; a duplicate app copy is harmless. */
+[x-cloak] {
+  display: none !important;
+}
+
 /* -- Smooth-load convention ------------------------------------------------
    Paired with layouts/studio/_smooth_load.html.erb (the Studio.smooth_load
    metas that opt Turbo into document.startViewTransition). These rules are

data/app/controllers/concerns/studio/error_handling.rb

@@ -189,13 +189,18 @@ module Studio
       raise e
     rescue StandardError => e
       error_log = create_error_log(e)
+      # `slug` is NOT in the engine's User contract (REQUIRED_USER_INSTANCE_METHODS
+      # is admin? + display_name), and `target` is routinely a User. Unguarded,
+      # the LOGGER raises NoMethodError and MASKS the original exception — the
+      # exact inverse of what this method exists to do. The name is a convenience
+      # column; its absence must never cost the record.
       if target
         error_log.target = target
-        error_log.target_name = target.slug
+        error_log.target_name = target.slug if target.respond_to?(:slug)
       end
       if parent
         error_log.parent = parent
-        error_log.parent_name = parent.slug
+        error_log.parent_name = parent.slug if parent.respond_to?(:slug)
       end
       error_log.save!
       @_error_logged = true

data/app/controllers/concerns/studio/link_consumption.rb

@@ -1,9 +1,28 @@
+# frozen_string_literal: true
+
 module Studio
-  # Shared create-or-login building blocks for the magic-link / link consume
-  # controllers (MagicLinksController + Studio::LinksController). `result` is
-  # anything responding to #email and #return_to — the legacy MagicLink::Result
-  # OR a Studio::Link — so both token schemes reuse this. Apps that override the
-  # link controllers (e.g. turf-monster's contest landing) include it too.
+  # The magic-link click, start to finish — shared by Studio::LinksController
+  # and by any app that draws its own token route (turf-monster's contest
+  # landing). Two entry points bracket the single-use burn:
+  #
+  #   preview_magic_link(link) — the GET. NEVER burns. Returns :live for a link
+  #       that is still good (the caller renders the scanner-safe interstitial),
+  #       and otherwise settles the click here and returns :handled.
+  #   consume_magic_link(link) — the POST. The one and only place a token burns.
+  #
+  # Both route their answer through Studio::LinkResolution, the pure decision
+  # table, so "what should this click do" has exactly one owner and the GET and
+  # the POST can never disagree about it. The invariant that table enforces:
+  # **a dead link never touches the session.**
+  #
+  # Apps customize by overriding the hooks at the bottom, not by re-deciding:
+  # sign_in_existing / sign_up_new (the authenticate path), link_continue (the
+  # viewer's own live link), link_dead (no session mutation, ever), plus
+  # link_login_path / link_home_path for apps whose sign-in page is not
+  # `login_path`.
+  #
+  # `link` is anything responding to #email, #return_to, #live?, #burn and
+  # #dead_status — in practice a Studio::Link, or nil for an unknown token.
   #
   # Relies on the host ApplicationController contract from Studio::ErrorHandling:
   # set_app_session, rescue_and_log, current_user, plus root_path / login_path.
@@ -12,12 +31,62 @@ module Studio
 
     private
 
+    # --- entry points ---------------------------------------------------------
+
+    # GET. Inert by construction: email scanners, link-preview fetchers and the
+    # Gmail image proxy all issue a GET against an emailed URL, so burning here
+    # would spend the token before the human ever clicked. A dead link is
+    # settled immediately rather than sent through a spinner that only POSTs to
+    # learn the same thing.
+    def preview_magic_link(link)
+      return :live if link&.live?
+
+      link_dead(resolve_link_click(link, status: dead_status_for(link)), link)
+      :handled
+    end
+
+    # POST. Burns first — the burn is atomic, so winning it IS the proof the
+    # link was live — then acts on what the burn returned.
+    def consume_magic_link(link)
+      claimed = link.present? && link.burn
+      outcome = resolve_link_click(link, status: claimed ? :claimed : dead_status_for(link))
+
+      case outcome.action
+      when :authenticate
+        user = User.find_by(email: link.email)
+        user ? sign_in_existing(user, link) : sign_up_new(link)
+      when :continue
+        link_continue(link, outcome)
+      else
+        link_dead(outcome, link)
+      end
+    end
+
+    def resolve_link_click(link, status:)
+      Studio::LinkResolution.call(
+        status:        status,
+        link_email:    link&.email,
+        session_email: current_user&.email
+      )
+    end
+
+    def dead_status_for(link)
+      link.nil? ? :unknown : link.dead_status
+    end
+
+    # --- outcomes -------------------------------------------------------------
+
     def sign_in_existing(user, result)
       set_app_session(user)
       # Clicking the link proves email ownership, so verify any account that
       # reached here without it (e.g. a Google/wallet-only signup).
-      user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at) && user.email_verified_at.blank?
-      redirect_to(safe_path(result.return_to) || root_path, notice: "Signed in. Welcome back!")
+      #
+      # rescue_and_log because this is a WRITE, and the session is already
+      # established above it: a consumer app with an extra User validation would
+      # otherwise turn a routine sign-in into a 500 the visitor sees while
+      # actually signed in, with nothing in ErrorLog to explain it.
+      rescue_and_log(target: user) { verify_email_ownership(user) }
+      redirect_to(link_destination(:return_to, result), notice: "Signed in. Welcome back!")
     end
 
     # Build → configure_new_user → save!. No password — email auth is link-only.
@@ -26,9 +95,9 @@ module Studio
       Studio.configure_new_user.call(user)
       rescue_and_log(target: user) do
         user.save!
-        user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at)
+        verify_email_ownership(user)
         set_app_session(user)
-        redirect_to(safe_path(result.return_to) || root_path, notice: Studio.welcome_message.call(user))
+        redirect_to(link_destination(:return_to, result), notice: Studio.welcome_message.call(user))
       end
     rescue ActiveRecord::RecordNotUnique
       # Two valid tokens for the same brand-new email consumed near-simultaneously
@@ -37,10 +106,61 @@ module Studio
       existing = User.find_by(email: result.email)
       return sign_in_existing(existing, result) if existing
 
-      redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
+      redirect_to link_login_path, alert: "We couldn't finish creating your account. Please try again."
     rescue StandardError => e
       Rails.logger.error("[Studio::LinkConsumption#sign_up_new] signup failed #{e.class}: #{e.message}")
-      redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
+      redirect_to link_login_path, alert: "We couldn't finish creating your account. Please try again."
+    end
+
+    # The viewer's own still-live link. The token burns (nobody replays it
+    # later) but the session is left exactly as it stands — re-authenticating
+    # would buy nothing and would cost a host that rotates the session on
+    # sign-in every scrap of state the visitor had built up. From the visitor's
+    # side this is indistinguishable from following a plain link, which is the
+    # entire point.
+    def link_continue(result, _outcome)
+      # Same write, same guard as sign_in_existing — and here the stakes are
+      # sharper still: this path exists to be invisible, so an unlogged 500 on a
+      # re-click would be the loudest thing about it.
+      rescue_and_log(target: current_user) { verify_email_ownership(current_user) }
+      redirect_to link_destination(:return_to, result)
+    end
+
+    # A used, expired, or unrecognized link. Touching the session here is the
+    # bug this whole concern was written to remove: the visitor's session has
+    # nothing to do with the state of a token someone mailed them.
+    def link_dead(outcome, result)
+      path = link_destination(outcome.destination, result)
+      return redirect_to(path) if outcome.silent?
+
+      redirect_to path, outcome.level => outcome.message
+    end
+
+    # --- hooks + helpers ------------------------------------------------------
+
+    def link_destination(destination, result)
+      case destination
+      when :login then link_login_path
+      when :home  then link_home_path
+      else             safe_path(result&.return_to) || link_home_path
+      end
+    end
+
+    # Where a visitor with NO session lands when the link is dead. Apps whose
+    # sign-in page is not `login_path` (turf-monster: signin_path) override this.
+    def link_login_path
+      login_path
+    end
+
+    # Where a click lands when the link's own destination is not ours to follow.
+    def link_home_path
+      root_path
+    end
+
+    def verify_email_ownership(user)
+      return unless user.respond_to?(:email_verified_at) && user.email_verified_at.blank?
+
+      user.update!(email_verified_at: Time.current)
     end
 
     # Only same-origin absolute paths survive; everything else collapses to nil.

data/app/controllers/concerns/studio/magic_link_issuing.rb

@@ -2,36 +2,31 @@
 
 module Studio
   # Minting a magic link, and building the URL that consumes it — the two halves
-  # of one decision (Studio.magic_link_store), kept in one place so they can
-  # never drift apart. A token minted in the :database store is only consumable
-  # at /l/<token>; a :signed token only at /magic_link/<token>. Handing out the
-  # wrong URL for the store yields an "invalid or expired link" on a link that
-  # was valid — the failure mode this concern exists to prevent.
+  # of one decision, kept in one place so they can never drift apart. Handing
+  # out the wrong URL for a token yields an "invalid or expired link" on a link
+  # that was perfectly valid: the failure mode this concern exists to prevent.
+  #
+  # Since 0.31.0 there is one store (a Studio::Link row) and one token format
+  # (Studio::LinkToken.generate — 16 URL-safe characters), so the only remaining
+  # question is the PATH: the standard /l/<token>, or an app's own token route
+  # (turf-monster keeps /magic_link/<token> because /l is already its
+  # landing-page namespace).
   #
   # Included by every issuer: MagicLinksController (the request-a-link flow),
-  # UserMailer (the emailed link), and Studio::LocalReviewsController (the
-  # dev-only local-review link). An app that overrides MagicLinksController
-  # wholesale brings its own issuing and is unaffected.
+  # RegistrationsController (the passwordless signup POST), UserMailer (the
+  # emailed link), and Studio::LocalReviewsController (the dev-only local-review
+  # link). An app that overrides those wholesale brings its own issuing.
   module MagicLinkIssuing
     extend ActiveSupport::Concern
 
     private
 
-    # Mint a token in the configured store. Default :signed keeps the legacy
-    # stateless MessageVerifier link; :database mints a Studio::Link row (the
-    # short, unified scheme). `return_to` is sanitized by both stores.
+    # Mint a token. `return_to` is sanitized to a same-origin path by the store.
     def issue_magic_link(email, return_to)
-      if Studio.magic_link_store == :database
-        Studio::Link.create_magic_link(email: email, return_to: return_to).token
-      else
-        MagicLink.generate(email: email, return_to: return_to)
-      end
+      Studio::Link.create_magic_link(email: email, return_to: return_to).token
     end
 
-    # The URL that CONSUMES the token this app mints: the short /l/<token> for
-    # the :database scheme, the legacy /magic_link/<token> for :signed (and for
-    # a :database app that keeps its own /magic_link route, e.g. turf-monster,
-    # whose /l is already its landing-page namespace).
+    # The URL that CONSUMES the token this app mints.
     def magic_link_url_for(token)
       Studio.magic_link_via_l_route? ? link_url(token: token) : magic_link_url(token: token)
     end