studio-engine 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be8862879ffbd78bccc84e617beb1bae213e57c76c91d421b1b64d8e9f5122ff
-  data.tar.gz: 8e8fbc3e9f4db83b65f4693aec67f58f183363e873869a89513c62215422345c
+  metadata.gz: c36ecfe3e213e5621f205743728461c24d02912ed7e7bbf5109e0c15afd3225e
+  data.tar.gz: d92755cdb2ed3f7b8dca941bb514e2c725314056afbc83ee7fb190a4cc4a993c
 SHA512:
-  metadata.gz: ae3fee306fed9857d3421c005ac4006f46dda013d95009a0cde4daf6fc010a6c2d604e8ea173d7806985807e8b5603c57e6cef392a2b2fd00943d3db050d645d
-  data.tar.gz: b629a74f76f684338f82e028e6a5833dd15289720da55fea4f25e08afa1549454bed48df1131f1338a8ac28880e9e86b9201765ab4c7aac043510eefe7a70797
+  metadata.gz: 17c9f349695792402a9cbcb245159ebcba107b355edcdc9c5ae3b3d89d23303d0bd3a4bd96846d1d23c23417fbff47a0f73e0db887bd8880faeb4687e7e48c12
+  data.tar.gz: c65f117c47ced22be63a3747f0cd2b283f00a80c40802947a1003ada976749242ebd8340a511d89c9806d9449c6a3525eb1cbebb5fdd47d37cf334465d2e2644

data/CHANGELOG.md

@@ -2,6 +2,160 @@
 
 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
@@ -94,7 +248,9 @@ are **unchanged** — their production hard-close still stands, which is also wh
 - **`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`). Omitting them is silent:
+  (~~`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,

data/README.md

@@ -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.
 

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

data/app/controllers/magic_links_controller.rb

@@ -1,24 +1,21 @@
-# Unified create-or-login email magic link (the passwordless email path).
+# Requesting a magic link — the passwordless email path's front door.
 #
-#   POST /magic_link        — request a link (email [, return_to])
-#   GET  /magic_link/:token — "Confirm sign-in" interstitial (does NOT consume)
-#   POST /magic_link/:token — consume it: log in OR create the account
+#   POST /magic_link — request a link (email [, return_to])
 #
-# create-or-login: clicking the link IS proof of email ownership, so an email
-# that collides with a Google/wallet-only account that was never email-verified
-# is safely logged in here and stamped email_verified_at (unlike from_omniauth,
-# which refuses that collision precisely because it lacked this proof).
+# That is the whole controller. The token-bearing half lives at /l/<token>
+# (Studio::LinksController): one token format, one place it burns. Before
+# 0.31.0 this class also owned a /magic_link/:token confirm+consume pair for
+# the retired :signed store, which was a second door onto the same lock.
 #
-# This is the engine's GENERIC base. Apps that need richer post-consume routing
-# (e.g. turf-monster's contest landing + picks rehydration + entry-tokens upsell)
-# OVERRIDE this controller in the app and reuse the MagicLink service + the
-# sign_in_existing / sign_up_new building blocks.
+# create-or-login: clicking the emailed link IS proof of email ownership, so an
+# email that collides with a Google/wallet-only account that was never
+# email-verified is safely signed in at consume time and stamped
+# email_verified_at (unlike from_omniauth, which refuses that collision
+# precisely because it lacked this proof).
 class MagicLinksController < ApplicationController
-  include Studio::LinkConsumption
   include Studio::MagicLinkIssuing
 
   skip_before_action :require_authentication
-  layout false, only: :confirm
 
   # Respond uniformly for any well-formed email. Under create-or-login every
   # address is "valid" (it logs in or signs up), so there is nothing to
@@ -26,7 +23,7 @@ class MagicLinksController < ApplicationController
   def create
     email = params[:email].to_s.strip.downcase
     if email.match?(URI::MailTo::EMAIL_REGEXP)
-      token = issue_magic_link(email, safe_path(params[:return_to]))
+      token = issue_magic_link(email, Studio::LinkToken.sanitize_path(params[:return_to]))
       Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
     end
     respond_to do |format|
@@ -35,31 +32,7 @@ class MagicLinksController < ApplicationController
     end
   end
 
-  # GET /magic_link/:token is deliberately inert. Email link scanners and link
-  # preview clients frequently prefetch emailed URLs with GET/HEAD; if GET burned
-  # the token, the human's first real click could already be invalid. The page
-  # renders a CSRF-protected form that a browser auto-POSTs to #consume.
-  def confirm
-    # strict-origin strips the token-bearing path from subresource Referer
-    # headers while preserving a usable Origin header for Rails' CSRF origin
-    # check on the consume POST.
-    response.set_header("Referrer-Policy", "strict-origin")
-    @token = params[:token]
-  end
-
-  # POST /magic_link/:token is the authoritative consume. This is the only place
-  # the single-use token is burned.
-  def consume
-    response.set_header("Referrer-Policy", "strict-origin")
-    result = MagicLink.consume(params[:token])
-    user = User.find_by(email: result.email)
-    user ? sign_in_existing(user, result) : sign_up_new(result)
-  rescue MagicLink::InvalidToken
-    redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
-  end
-
-  # issue_magic_link (mint in the configured store) comes from
+  # issue_magic_link (mint a Studio::Link row) comes from
   # Studio::MagicLinkIssuing, shared with UserMailer — which builds the URL that
   # consumes it — so the mint and its landing URL cannot drift apart.
-  # sign_in_existing / sign_up_new / safe_path come from Studio::LinkConsumption.
 end

data/app/controllers/registrations_controller.rb

@@ -1,4 +1,6 @@
 class RegistrationsController < ApplicationController
+  include Studio::MagicLinkIssuing
+
   skip_before_action :require_authentication
 
   def new
@@ -13,7 +15,7 @@ class RegistrationsController < ApplicationController
     unless Studio.auth_method?(:password)
       email = (params.dig(:user, :email) || params[:email]).to_s.strip.downcase
       if email.match?(URI::MailTo::EMAIL_REGEXP)
-        token = MagicLink.generate(email: email)
+        token = issue_magic_link(email, nil)
         Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
       end
       return redirect_to login_path, notice: "Check your inbox — we just emailed you a sign-in link."

data/app/controllers/studio/links_controller.rb

@@ -1,6 +1,6 @@
 module Studio
-  # The unified short-token link entry point — GET/POST /l/<token>. Dispatches by
-  # Studio::Link#kind:
+  # The short-token link entry point — GET/POST /l/<token>, the only magic-link
+  # door the engine draws. Dispatches by Studio::Link#kind:
   #
   #   magic_link → scanner-safe confirm interstitial (GET, inert) that auto-POSTs
   #                to #consume, the ONLY place the single-use token is burned +
@@ -9,6 +9,10 @@ module Studio
   #                the link's target (or root). Reusable + safe to prefetch, so
   #                GET does the work (no POST step).
   #
+  # Every decision about what a magic-link click DOES lives in
+  # Studio::LinkConsumption / Studio::LinkResolution, not here — including the
+  # invariant that a dead link leaves the visitor's session untouched.
+  #
   # Namespaced (not top-level Links) because mcritchie-studio already owns a
   # public /links linktree (top-level LinksController). Apps needing richer
   # post-consume routing (contest landing, picks rehydration, age-gate) define
@@ -25,30 +29,24 @@ module Studio
       response.set_header("Referrer-Policy", "strict-origin")
       @link = Studio::Link.find_by(token: params[:token])
 
-      case @link&.kind
-      when "magic_link"
-        @token = params[:token]
-        render :confirm
-      when "referral"
+      if @link&.kind == "referral"
         capture_referral(@link)
-        redirect_to(@link.target || root_path)
-      else
-        redirect_to login_path, alert: "That link is invalid or has expired. Request a fresh one below."
+        return redirect_to(@link.target || root_path)
       end
+
+      # A magic link, or a token with no row behind it. preview_magic_link is
+      # inert — it never burns — and settles a dead link itself rather than
+      # sending the visitor through a spinner that only POSTs to learn the same.
+      @token = params[:token]
+      render :confirm if preview_magic_link(@link&.kind == "magic_link" ? @link : nil) == :live
     end
 
     # POST /l/:token — authoritative magic-link consume. Only magic_link kinds are
-    # consumable here; referral links are reusable and handled entirely on GET.
+    # consumable here; referral links are reusable and handled entirely on GET,
+    # so a referral token scoped out below reads as an unknown token.
     def consume
       response.set_header("Referrer-Policy", "strict-origin")
-      link = Studio::Link.find_by(token: params[:token])
-      raise Studio::Link::InvalidToken, "not a magic link" unless link&.kind == "magic_link"
-
-      link.consume! # burns the single-use token; raises if already used / expired
-      user = User.find_by(email: link.email)
-      user ? sign_in_existing(user, link) : sign_up_new(link)
-    rescue Studio::Link::InvalidToken
-      redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
+      consume_magic_link(Studio::Link.magic_links.find_by(token: params[:token]))
     end
 
     private

data/app/controllers/studio/local_reviews_controller.rb

@@ -30,10 +30,10 @@ module Studio
       email = Studio::LinkToken.normalize_email(params[:email])
       return redirect_to(login_path, alert: MISSING_EMAIL) unless email.match?(URI::MailTo::EMAIL_REGEXP)
 
-      # return_to is passed through raw: BOTH stores sanitize it to a same-origin
-      # path on the way in (Studio::Link.create_magic_link and MagicLink.generate
-      # each call Studio::LinkToken.sanitize_path). Re-sanitizing here would be a
-      # second spelling of a rule that already has one owner — and a mutation run
+      # return_to is passed through raw: the store sanitizes it to a same-origin
+      # path on the way in (Studio::Link.create_magic_link calls
+      # Studio::LinkToken.sanitize_path). Re-sanitizing here would be a second
+      # spelling of a rule that already has one owner — and a mutation run
       # confirmed it guards nothing the store does not already guard.
       token = issue_magic_link(email, params[:return_to])
       redirect_to magic_link_url_for(token), allow_other_host: false

data/app/mailers/user_mailer.rb

@@ -1,8 +1,7 @@
 class UserMailer < ApplicationMailer
-  # magic_link_url_for — the URL that consumes the token, matched to
-  # Studio.magic_link_store. Shared with the issuers that MINT the token
-  # (MagicLinksController, Studio::LocalReviewsController) so the two halves
-  # cannot drift apart.
+  # magic_link_url_for — the URL that consumes the token. Shared with the
+  # issuers that MINT it (MagicLinksController, RegistrationsController,
+  # Studio::LocalReviewsController) so the two halves cannot drift apart.
   include Studio::MagicLinkIssuing
 
   # Branded shell (banner + card) for engine-sent UserMailer emails. An app with
@@ -10,9 +9,11 @@ class UserMailer < ApplicationMailer
   layout "branded_mailer"
 
   # Passwordless sign-in link. `email` is a raw string (the recipient may not
-  # have an account yet). Token is a signed MagicLink payload (email + return_to
-  # + jti, single-use). Clicking the link logs the recipient in or creates their
-  # account. App-name-aware so the same template serves every Studio app.
+  # have an account yet). The token is a Studio::Link row's short token — 16
+  # URL-safe characters, single-use, expiring — and the email + return_to it
+  # stands for stay in the row, off the wire. Clicking the link logs the
+  # recipient in or creates their account. App-name-aware so the same template
+  # serves every Studio app.
   #
   # Engine GENERIC base. An app needing richer copy (e.g. turf-monster's
   # contest-aware variant) defines its own UserMailer, which wins.

data/app/models/studio/link.rb

@@ -11,13 +11,20 @@ module Studio
   # discriminator. Replaces the engine's stateless MessageVerifier MagicLink
   # service for mcritchie-studio so both apps share one short-token scheme.
   #
-  # Like Studio::EmailDelivery, the table lives in each consumer app (copy the
-  # reference migration in db/migrate); this model is shipped by the gem.
+  # Like Studio::EmailDelivery, the table lives in each consumer app — installed
+  # by `bin/rails studio_engine:install:migrations`, never hand-copied (a hand
+  # copy collides with the task's own copy on `class CreateStudioLinks`). This
+  # model is shipped by the gem.
   class Link < ApplicationRecord
     self.table_name = "studio_links"
 
     class InvalidToken < StandardError; end
 
+    # The app enabled :magic_link but never installed the table. Raised in place
+    # of a bare PG::UndefinedTable so the first person to hit it reads the fix
+    # instead of an adapter error — see mint!.
+    class MissingTable < StandardError; end
+
     belongs_to :linkable, polymorphic: true, optional: true
 
     validates :kind, inclusion: { in: Studio::LinkToken::KINDS }
@@ -76,6 +83,16 @@ module Studio
 
       # create! with a fresh random token, retrying the (astronomically rare)
       # unique-index collision a couple of times before surfacing the error.
+      #
+      # The MissingTable rescue exists because every consumer pins the engine as
+      # `~> 0.x`, which admits any release below 1.0 — so an app that never
+      # installed this table picks up the row store on its next `bundle update`
+      # whether or not anyone adopted it deliberately. Its boot is fine (nothing
+      # touches the table until someone signs in), and the failure then lands as
+      # a bare PG::UndefinedTable on a real person's sign-in. Naming the fix
+      # there is the difference between a five-minute repair and an outage
+      # nobody can read. The check is `table_exists?`, not a message match, so
+      # it holds on any adapter and never swallows an unrelated failure.
       def mint!(attrs)
         3.times do
           return create!(attrs.merge(token: Studio::LinkToken.generate))
@@ -83,6 +100,14 @@ module Studio
           next
         end
         create!(attrs.merge(token: Studio::LinkToken.generate))
+      rescue ActiveRecord::StatementInvalid
+        raise if table_exists?
+
+        raise MissingTable,
+              "studio-engine magic links need the studio_links table, and #{Studio.app_name} has no " \
+              "such table. Run `bin/rails studio_engine:install:migrations && bin/rails db:migrate` " \
+              "(install ALL of them). Do not hand-copy the migration — it collides with the task's " \
+              "own copy on `class CreateStudioLinks`."
       end
     end
 
@@ -106,6 +131,34 @@ module Studio
       self
     end
 
+    # The non-raising sibling of #consume!, and the one the click flow uses.
+    # Returns whether THIS caller won the burn — false for a link that was
+    # already used, has expired, or lost the atomic race to a concurrent click.
+    #
+    # Why a boolean and not the exception: "the link was dead" is not an error
+    # here, it is one of the two normal outcomes, and the branch it feeds
+    # (Studio::LinkResolution) needs the answer as data. Reloads on a loss so
+    # the caller reads the row's settled state (consumed_at / expires_at) rather
+    # than the copy it held before the race.
+    def burn
+      consume!
+      true
+    rescue InvalidToken
+      reload
+      false
+    end
+
+    # How a failed burn should be described. Only meaningful once #burn has
+    # returned false (or on a link that was never burned at all).
+    def dead_status
+      return :used if single_use? && consumed?
+      return :expired if expired?
+
+      # Neither flag is set but the burn did not land: a concurrent click won
+      # it between our read and our write. Same story for the reader.
+      :used
+    end
+
     def single_use?
       Studio::LinkToken.single_use?(kind)
     end

data/app/views/studio/_confirm_interstitial.html.erb

@@ -1,9 +1,10 @@
 <%#
   Shared scanner-safe sign-in interstitial. The GET that renders this is inert;
   the page auto-POSTs the CSRF-protected form to `consume_path` (the only place
-  a single-use token is burned). Used by both MagicLinksController#confirm
-  (consume_path: magic_link_consume_path) and Studio::LinksController#show
-  (consume_path: link_consume_path). Rendered with layout false (full document).
+  a single-use token is burned). Rendered by Studio::LinksController#show
+  (consume_path: link_consume_path) — the engine's only token door since 0.31.0
+  — and by any app drawing its own token route. Rendered with layout false
+  (full document).
 
   Local: consume_path — the POST target that burns the token + signs in.
 %>

data/db/migrate/20260620000002_allow_null_image_cache_owner.rb

@@ -3,6 +3,16 @@
 # migration; each consumer app installs its own copy (the table is app-owned).
 class AllowNullImageCacheOwner < ActiveRecord::Migration[7.2]
   def change
+    # No-op on an app that doesn't use ImageCache. `image_caches` is app-owned,
+    # so an app can install the engine's migrations without having that table —
+    # and unguarded, this raised and failed the whole `db:migrate`.
+    #
+    # Deleting the copy is NOT 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. The guard has to live
+    # here, in the migration, or it doesn't hold.
+    return unless table_exists?(:image_caches)
+
     change_column_null :image_caches, :owner_type, true
     change_column_null :image_caches, :owner_id, true
   end

data/lib/studio/link_resolution.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "link_token"
+
+module Studio
+  # What a magic-link click should DO — the whole decision as one pure table,
+  # free of ActiveRecord and of the controller, so every cell is unit-testable.
+  #
+  # A click has three inputs: whether this caller BURNED the link (won the
+  # single-use race), whose email the link carries, and who is already signed
+  # in. Six cells fall out of that, and one invariant runs through them:
+  #
+  #   **A dead link never touches the session.**
+  #
+  # Before this table, every dead token — used, expired, or unknown — ended at
+  # `redirect_to login_path, alert: "invalid or has expired"`, whatever session
+  # the visitor was holding. So clicking your own link a second time dumped you
+  # on a sign-in page, which reads as being logged out. It never was: the cookie
+  # survived, but the destination said otherwise. Now a dead link is at worst a
+  # notice, and at best silent.
+  #
+  # The table (rows = link state, columns = who is signed in):
+  #
+  #                | nobody          | 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
+  #
+  # `:continue` is the cell the operator asked for by name: a second click on
+  # your own still-live link must be "no material difference — just a redirect".
+  # It burns the token (so nobody replays it later) and deliberately does NOT
+  # re-authenticate, because a host that rotates the session on sign-in — as
+  # turf-monster does — would otherwise charge a re-click the price of every
+  # scrap of session state the visitor had built up.
+  module LinkResolution
+    # How the click found the link.
+    #   :claimed — this caller burned a live link (the only status that authenticates)
+    #   :used    — the row exists and was already consumed, or lost the burn race
+    #   :expired — the row exists and is past expires_at
+    #   :unknown — no row for this token, or the token is not a magic link
+    STATUSES = %i[claimed used expired unknown].freeze
+
+    # :authenticate — establish a session for the link's email (sign in or sign up)
+    # :continue     — the viewer already IS the link's user: keep the session as
+    #                 it stands and land them on the link's destination
+    # :dead         — do not touch the session at all
+    ACTIONS = %i[authenticate continue dead].freeze
+
+    # Where the click lands.
+    #   :return_to — the link's own destination (falling back to home)
+    #   :home      — the app root; used when the link belongs to someone else,
+    #                so its destination is not ours to follow
+    #   :login     — the sign-in page; only ever for a visitor with no session
+    DESTINATIONS = %i[return_to home login].freeze
+
+    Outcome = Struct.new(:action, :destination, :message, :level, keyword_init: true) do
+      def authenticate?
+        action == :authenticate
+      end
+
+      def continue?
+        action == :continue
+      end
+
+      def dead?
+        action == :dead
+      end
+
+      # A silent outcome shows the visitor nothing — the "no material
+      # difference" re-click.
+      def silent?
+        message.nil?
+      end
+    end
+
+    module_function
+
+    # @param status [Symbol] one of STATUSES
+    # @param link_email [String, nil] the email the link signs in (nil = unknown token)
+    # @param session_email [String, nil] the currently signed-in user's email
+    # @return [Outcome]
+    def call(status:, link_email: nil, session_email: nil)
+      raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
+
+      own = own_link?(link_email, session_email)
+
+      if status == :claimed
+        return Outcome.new(action: :continue, destination: :return_to) if own
+
+        # Nobody signed in, or somebody else signed in: both establish a session
+        # for the link's email. The second case is the deliberate account switch
+        # — a live link is proof of ownership, so it outranks the open session.
+        return Outcome.new(action: :authenticate, destination: :return_to)
+      end
+
+      # Dead from here down: no branch below may write to the session.
+      return Outcome.new(action: :dead, destination: :return_to) if own
+
+      if Studio::LinkToken.normalize_email(session_email).empty?
+        Outcome.new(action: :dead, destination: :login, level: :alert,
+                    message: dead_message(status: status, link_email: link_email))
+      else
+        Outcome.new(action: :dead, destination: :home, level: :notice,
+                    message: dead_message(status: status, link_email: link_email,
+                                          session_email: session_email))
+      end
+    end
+
+    # Same email, both sides present. A blank on either side is never a match —
+    # an unknown token (no email) must not read as "your own link" just because
+    # nobody is signed in.
+    def own_link?(link_email, session_email)
+      link = Studio::LinkToken.normalize_email(link_email)
+      seat = Studio::LinkToken.normalize_email(session_email)
+      !link.empty? && link == seat
+    end
+
+    # The notice a dead link earns. It names the address the link was for and
+    # why it failed — the detail that turns "something went wrong" into a
+    # decision the reader can act on — and, when a session is open, says so
+    # plainly, because the whole point is that nothing was lost.
+    def dead_message(status:, link_email: nil, session_email: nil)
+      addressee = Studio::LinkToken.normalize_email(link_email)
+      who = addressee.empty? ? "" : " for #{addressee}"
+      why = case status
+            when :expired then "has expired"
+            when :used    then "was already used"
+            else               "is no longer valid"
+            end
+
+      base = "That sign-in link#{who} #{why}."
+      seat = Studio::LinkToken.normalize_email(session_email)
+      return "#{base} Request a fresh one below." if seat.empty?
+
+      "#{base} You are still signed in as #{seat} — request a fresh link to switch accounts."
+    end
+  end
+end

data/lib/studio/link_token.rb

@@ -18,10 +18,19 @@ module Studio
     # they are deliberately NOT single-use.
     SINGLE_USE_KINDS = %w[magic_link].freeze
 
-    # 96 bits of entropy → ~16 URL-safe chars (e.g. "PP-PDbEj5V3-aNh4"). Short
-    # enough to keep the URL clean, far too large to brute-force — especially
-    # for single-use, expiring magic links. Matches turf-monster's proven format.
-    TOKEN_BYTES = 12
+    # THE HOUSE TOKEN STANDARD: 12 random bytes → exactly 16 URL-safe
+    # characters (e.g. "PP-PDbEj5V3-aNh4"). 96 bits of entropy — short enough
+    # that the whole link fits on one line of an email, far too large to
+    # brute-force, especially for a single-use token that expires in minutes.
+    #
+    # 16 sits mid-range in the house bound of 10-20 characters (TOKEN_LENGTH_
+    # BOUNDS), which is the number a reader should sanity-check a link against.
+    # urlsafe_base64 emits 4 characters per 3 bytes with no padding, so the
+    # length is exact, not approximate — every token is the same width.
+    TOKEN_BYTES  = 12
+    TOKEN_LENGTH = 16
+    TOKEN_LENGTH_BOUNDS = (10..20).freeze
+    TOKEN_FORMAT = /\A[A-Za-z0-9_-]+\z/
 
     module_function
 

data/lib/studio/theme_resolver.rb

@@ -48,7 +48,8 @@ module Studio
         "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
         "--color-success"        => colors[:success] || "#4BAF50",
         "--color-warning"        => colors[:warning] || "#FF7C47",
-        "--color-danger"         => colors[:danger] || "#EF4444"
+        "--color-danger"         => colors[:danger] || "#EF4444",
+        "--color-accent"         => colors[:accent] || "#F72585"
       }
     end
 
@@ -92,7 +93,8 @@ module Studio
         "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
         "--color-success"        => colors[:success] || "#4BAF50",
         "--color-warning"        => colors[:warning] || "#FF7C47",
-        "--color-danger"         => colors[:danger] || "#EF4444"
+        "--color-danger"         => colors[:danger] || "#EF4444",
+        "--color-accent"         => colors[:accent] || "#F72585"
       }
     end
   end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.30.0"
+  VERSION = "0.31.0"
 end

data/lib/studio.rb

@@ -9,6 +9,7 @@ require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
 require "studio/link_token"
+require "studio/link_resolution"
 require "studio/email"
 require "studio/email_smoke"
 require "studio/mail_transport"
@@ -80,18 +81,40 @@ module Studio
   #   end
   mattr_accessor :sidebar_sections, default: []
 
-  # Magic-link (passwordless email) tuning. token_name keys the MessageVerifier
-  # purpose; bump it to invalidate every outstanding link. See MagicLink service.
-  mattr_accessor :magic_link_ttl,        default: 15.minutes
+  # How long a freshly minted magic link stays live.
+  mattr_accessor :magic_link_ttl, default: 15.minutes
+
+  # RETIRED (0.31.0) — kept only so an initializer that still sets it boots.
+  # It named the MessageVerifier purpose for the old :signed store, which no
+  # longer exists. Delete the line from your initializer.
   mattr_accessor :magic_link_token_name, default: "magic_link_v1"
 
-  # Where magic-link tokens are stored / which URL scheme they use.
-  #   :signed   (default) — stateless MessageVerifier MagicLink service; URL is
-  #             /magic_link/<long token>. No table needed. Back-compat default.
-  #   :database — a Studio::Link row; URL is the short /l/<token>. Requires the
-  #             studio_links table (install the reference migration). The
-  #             unified scheme both apps move to.
-  mattr_accessor :magic_link_store, default: :signed
+  # RETIRED (0.31.0) — magic links are ALWAYS Studio::Link rows now, so this
+  # reads :database and nothing else. Assigning :signed raises rather than
+  # silently downgrading: that store minted a ~350-character MessageVerifier
+  # blob whose EXPIRED form cannot be decoded, so an app on it could not tell
+  # whose dead link it was holding — which is exactly the fact
+  # Studio::LinkResolution needs to leave a live session alone. Requires the
+  # studio_links table, installed by `bin/rails studio_engine:install:migrations`
+  # (never hand-copied — a hand copy collides with the task's own copy on
+  # `class CreateStudioLinks`).
+  mattr_reader :magic_link_store, default: :database
+
+  # `to_s.to_sym`, not `to_sym`: this runs from an initializer, and nil or an
+  # Integer would raise NoMethodError — swallowing the explanation below with a
+  # message that says nothing about what to do. A blank falls through to the
+  # raise instead, so the operator reads the actual instruction.
+  def self.magic_link_store=(value)
+    return if value.to_s.to_sym == :database
+
+    raise ArgumentError,
+          "Studio.magic_link_store = #{value.inspect} is retired (studio-engine 0.31.0). " \
+          "Magic links are Studio::Link rows served at /l/<token>. Delete this line from " \
+          "config/initializers/studio.rb, then install the table with " \
+          "`bin/rails studio_engine:install:migrations && bin/rails db:migrate` — in that " \
+          "order, because this raise fires while the initializer loads and no rake task can " \
+          "boot until the line is gone."
+  end
 
   # Whether Studio.routes draws the magic_link + solana wallet routes. An app that
   # already defines its own auth routes (e.g. turf-monster, which has battle-tested
@@ -229,13 +252,13 @@ module Studio
     false
   end
 
-  # True when the emailed/inbox magic-link URL is the short /l/<token> — i.e.
-  # magic links are Studio::Link rows AND this app draws the /l routes. False =
-  # the legacy /magic_link/<token> path: the :signed store, OR an app on the
-  # :database store that keeps its own /magic_link route (e.g. turf-monster,
-  # whose /l is already its landing-page namespace).
+  # True when the emailed/inbox magic-link URL is the short /l/<token> — the
+  # standard. False means this app draws its own token route instead and owns
+  # the matching consume: turf-monster keeps /magic_link/<token> because /l is
+  # already its landing-page namespace. Either way the TOKEN is the same short
+  # Studio::Link token; only the path in front of it differs.
   def self.magic_link_via_l_route?
-    magic_link_store == :database && draw_link_routes
+    draw_link_routes
   end
 
   # The floor every developer-desk tool sits on: the local email inbox
@@ -393,18 +416,15 @@ module Studio
         get "_studio/local_review", to: "studio/local_reviews#show",  as: :studio_local_review
       end
 
-      # Passwordless email (magic link). Helpers: magic_link_request_path (POST
-      # to request a link), magic_link_path(token) / magic_link_url(token:)
-      # for the emailed GET confirmation page, and magic_link_consume_path(token)
-      # for the scanner-safe POST consume. The token is a URL-safe
-      # MessageVerifier blob but the constraint guards against a stray "."
-      # segment.
+      # Passwordless email (magic link) — the REQUEST half only. Helper:
+      # magic_link_request_path (POST an email address, get a link mailed).
+      #
+      # The token-bearing half moved to /l/<token> below (0.31.0). There is one
+      # token format now — a short Studio::Link row — and one place that burns
+      # it, so the old /magic_link/:token confirm+consume pair would have been a
+      # second door onto the same lock.
       if Studio.draw_auth_routes && Studio.auth_method?(:magic_link)
-        post "magic_link",        to: "magic_links#create",   as: :magic_link_request
-        get  "magic_link/:token", to: "magic_links#confirm",  as: :magic_link,
-             constraints: { token: %r{[^/]+} }
-        post "magic_link/:token", to: "magic_links#consume",  as: :magic_link_consume,
-             constraints: { token: %r{[^/]+} }
+        post "magic_link", to: "magic_links#create", as: :magic_link_request
       end
 
       # Unified short-token links — /l/<token> for magic sign-in links + referral

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -220,7 +220,6 @@ files:
 - app/models/studio/model_page.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
-- app/services/magic_link.rb
 - app/services/studio/email_image.rb
 - app/views/components/_admin_dropdown.html.erb
 - app/views/components/_avatar.html.erb
@@ -247,7 +246,6 @@ files:
 - app/views/layouts/studio/_flash.html.erb
 - app/views/layouts/studio/_head.html.erb
 - app/views/layouts/studio/_smooth_load.html.erb
-- app/views/magic_links/confirm.html.erb
 - app/views/navbar/show.html.erb
 - app/views/registrations/new.html.erb
 - app/views/schema/index.html.erb
@@ -336,6 +334,7 @@ files:
 - lib/studio/engine.rb
 - lib/studio/environment_banner.rb
 - lib/studio/image_cache.rb
+- lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
 - lib/studio/mail_transport.rb
 - lib/studio/redis.rb

data/app/services/magic_link.rb

@@ -1,122 +0,0 @@
-# Unified create-or-login magic link.
-#
-# A magic link is a signed, short-lived, single-use token keyed on an EMAIL
-# (the user may not exist yet — clicking the link either logs them in or
-# creates the account). The token is a `message_verifier(token_name)` payload
-# carrying the email + a sanitized return_to + a random jti.
-#
-# Single-use is enforced with the jti: on `generate` we record the jti in
-# Rails.cache (Redis, cross-process); on `consume` we delete it and reject if
-# it was already gone (replay / second click). The signature already covers
-# tamper + expiry; the jti closes the replay gap.
-#
-# Token name + TTL come from Studio config (Studio.magic_link_token_name /
-# Studio.magic_link_ttl) so each app can tune them; the jti cache entry is
-# always given a few extra minutes so a still-valid token's jti is present.
-#
-# NOTE on test env: the test cache is :null_store, where writes/deletes are
-# no-ops and `delete` always returns false — enforcing single-use there would
-# reject every legitimate consume. So enforcement is skipped for non-tracking
-# stores; the service unit test injects a real MemoryStore to exercise it.
-#
-# Lifted into studio-engine (was turf-monster app/services/magic_link.rb).
-class MagicLink
-  # Back-compat defaults. Behavior is driven by the `token_name` / `ttl` methods
-  # (which read Studio config); these constants remain so existing consumer code
-  # /tests referencing MagicLink::TTL keep working, and they equal the config
-  # defaults.
-  TOKEN_KEY = "magic_link_v1"
-  TTL       = 15.minutes
-
-  class InvalidToken < StandardError; end
-
-  Result = Struct.new(:email, :return_to, keyword_init: true)
-
-  class << self
-    # Test seam — defaults to Rails.cache. The service unit test sets this to
-    # an ActiveSupport::Cache::MemoryStore to assert single-use, then resets it.
-    attr_writer :cache
-
-    def cache
-      @cache || Rails.cache
-    end
-
-    def token_name
-      Studio.magic_link_token_name
-    end
-
-    def ttl
-      Studio.magic_link_ttl
-    end
-
-    # jti outlives the token so a valid token's jti is always still present.
-    def jti_ttl
-      ttl + 5.minutes
-    end
-
-    # Returns a signed token string. `return_to` is sanitized to a local path.
-    # The MessageVerifier blob is standard base64 (can contain "/" and "+"),
-    # which breaks the `%r{[^/]+}` route constraint once the payload is large
-    # enough to emit a "/". Wrap it URL-safe so the token is always
-    # [A-Za-z0-9_-]=, matching the route and surviving URL generation.
-    def generate(email:, return_to: nil)
-      normalized = normalize_email(email)
-      jti = SecureRandom.hex(16)
-      cache.write(jti_key(jti), normalized, expires_in: jti_ttl) if enforce_single_use?
-      raw = verifier.generate(
-        { email: normalized, return_to: sanitize_path(return_to), jti: jti, v: 1 },
-        expires_in: ttl
-      )
-      Base64.urlsafe_encode64(raw)
-    end
-
-    # Verifies signature + expiry + single-use. Returns a Result or raises
-    # InvalidToken. Idempotency is NOT offered — a consumed token is dead.
-    def consume(token)
-      raw = Base64.urlsafe_decode64(token.to_s)
-      payload = verifier.verify(raw).with_indifferent_access
-      raise InvalidToken, "unexpected token shape" unless payload[:v] == 1 && payload[:email].present?
-
-      if enforce_single_use?
-        # delete returns true only when the jti was still present
-        raise InvalidToken, "link already used or expired" unless cache.delete(jti_key(payload[:jti]))
-      elsif !Rails.env.test?
-        # Single-use is disabled (non-tracking cache). Expected in :null_store
-        # dev; in any other env it means replay protection is silently OFF —
-        # tokens are replayable for their TTL. Surface it loudly.
-        Rails.logger.warn("[MagicLink] single-use NOT enforced (cache=#{cache.class}); links are replayable until expiry")
-      end
-
-      Result.new(email: payload[:email], return_to: sanitize_path(payload[:return_to]))
-    rescue ActiveSupport::MessageVerifier::InvalidSignature, ArgumentError
-      # ArgumentError → malformed base64 (tampered/truncated token).
-      raise InvalidToken, "invalid or expired link"
-    end
-
-    private
-
-    def verifier
-      Rails.application.message_verifier(token_name)
-    end
-
-    def jti_key(jti)
-      "magic_link/jti/#{jti}"
-    end
-
-    def normalize_email(email)
-      email.to_s.strip.downcase
-    end
-
-    # Only same-origin absolute paths survive; everything else (protocol-relative
-    # "//evil", absolute URLs, blank) collapses to nil so callers fall back to a
-    # default redirect.
-    def sanitize_path(path)
-      p = path.to_s
-      p.start_with?("/") && !p.start_with?("//") ? p : nil
-    end
-
-    def enforce_single_use?
-      !cache.is_a?(ActiveSupport::Cache::NullStore)
-    end
-  end
-end

data/app/views/magic_links/confirm.html.erb

@@ -1,2 +0,0 @@
-<%# Legacy /magic_link/:token interstitial. Shared body in studio/_confirm_interstitial. %>
-<%= render "studio/confirm_interstitial", consume_path: magic_link_consume_path(token: @token) %>