studio-engine 0.30.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be8862879ffbd78bccc84e617beb1bae213e57c76c91d421b1b64d8e9f5122ff
-  data.tar.gz: 8e8fbc3e9f4db83b65f4693aec67f58f183363e873869a89513c62215422345c
+  metadata.gz: 445252feafe8e5767f83fcfc37ef8278a39e3cf02c10f050e1e89eb0f1dc779e
+  data.tar.gz: f99cd313622b6eaa1b94a4d20bd4d2b2bca026f9c44899e0a94cdfef2c18a19c
 SHA512:
-  metadata.gz: ae3fee306fed9857d3421c005ac4006f46dda013d95009a0cde4daf6fc010a6c2d604e8ea173d7806985807e8b5603c57e6cef392a2b2fd00943d3db050d645d
-  data.tar.gz: b629a74f76f684338f82e028e6a5833dd15289720da55fea4f25e08afa1549454bed48df1131f1338a8ac28880e9e86b9201765ab4c7aac043510eefe7a70797
+  metadata.gz: 67d422357f8bfe80704d7c61dcdfce194f86dd902d460837ec85424db4fe3a804d41516213fe2c8e171c304bca120c3b70af460f8b9df5c8bbc4f39993dafabc
+  data.tar.gz: cbcd30b10f5f9680ad79f60f541eca0afbc93e824522c914350e2f63cb4b4f47ba3bc48c4cd25afa9bc73ada4a9dbba08321b82c094651a63998eebf7dfbdf1a

data/CHANGELOG.md

@@ -2,6 +2,178 @@
 
 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.32.0 — Unreleased
+
+**Readable ink on every theme, and the `btn-primary` label joins the token
+contract.** (The token work merged after 0.31.0 was cut, so both land here.)
+
+Dark- and light-mode `--color-text-muted` / `--color-text-secondary` no longer
+hardcode slate grays: they derive from the theme base by a bounded contrast
+search (`ColorScale.contrast_ratio` is new public API) that walks the blend
+until the ink clears 3:1 / 4.5:1 on every emitted background — for any
+operator-picked base, not just the fleet's. Fixed grays measured as low as
+2.05:1 on themed surfaces.
+
+Consumers can now also set `--btn-primary-fg` (and `--btn-primary-fg-hover`
+for the darker hover fill) on `:root` exactly like the existing
+`--btn-secondary-*` tokens; a light brand primary (McRitchie Industries'
+furnace orange) fails WCAG under the hardcoded white label. Defaults resolve
+to the same white as before, so tokenless consumers are unchanged.
+
+## 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 +266,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/assets/tailwind/studio_engine/engine.css

@@ -71,6 +71,8 @@
   ADDITIVE in Tailwind v4 (both definitions emit and the engine's rules leak in),
   so forking is not a clean override. Set these on :root in the consumer's CSS:
 
+    --btn-primary-fg              label color    (default: #fff)
+    --btn-primary-fg-hover        hover label    (default: same as --btn-primary-fg)
     --btn-secondary-bg            base fill      (default: var(--color-success))
     --btn-secondary-bg-hover      hover fill     (default: same as base)
     --btn-secondary-hover-filter  hover filter   (default: brightness(0.9))
@@ -97,10 +99,18 @@
   }
 }
 
+/* btn-primary's label is token-overridable like btn-secondary's fill: a light
+   brand primary (e.g. industries' furnace orange) fails contrast under a white
+   label, so such apps set --btn-primary-fg (and, when the darker hover fill
+   flips the readable choice, --btn-primary-fg-hover) instead of fighting the
+   @utility with unlayered overrides. Defaults resolve to the same white as
+   before (a literal #fff — the engine's both-modes guard bars raw
+   --color-white references, which only exist in Tailwind's compiled theme). */
 @utility btn-primary {
-  @apply text-white;
+  color: var(--btn-primary-fg, #fff);
   background-color: var(--color-cta);
   &:hover {
+    color: var(--btn-primary-fg-hover, var(--btn-primary-fg, #fff));
     background-color: var(--color-cta-hover);
   }
 }

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