studio-engine 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 202706aa6f71348f59cb10a90dd7c726c199ad6399586f68d9ea5177600dd427
-  data.tar.gz: 24cb9f251d83853e295a88f8ae4d0ba5bab0e447d967f25afe72d1ecdf25317d
+  metadata.gz: f49b9ef9699144b785efbe7d4839261bba26035970a6c411f5cd54d0606ea97c
+  data.tar.gz: 3705abb5871fcfaa48b7c55613b0bc430b275c8bf9eb4c1625e43fcf14cfed32
 SHA512:
-  metadata.gz: ceccb972024f66226009cace56334f895e60384ad613a7063eceb90191e2c9fc5582b64422f4234cb4a136443a33558e5cda856e55eef76264e8d4b62eff432c
-  data.tar.gz: 435a7cad0e8c0af35b43439841c9fd1e714ebdec7d0e894f9526cde29be6d3d1437ffd6247ff760dd6766b8a52602fb12f0148a6b1002cfe1d830b16b75155f1
+  metadata.gz: 584cbbcdeeb388b1a6b0115a790fb6fa3d1c4ce4c69f42e57f7f0985edb4f6338578db04dcfeb5c60bde65aada69509db87c07151a52aab9f9348739a332cdca
+  data.tar.gz: dbbe745f30a632c21d528e336dd323a21224e71d39f97caf6fc43f68f958d1cb78da1a8660d735393847bdfeb67a79d15c1f12c199446f665c0267ff521c19fd

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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.19.0 — 2026-07-27
+
+### Added
+
+- **`GET /_studio/local_review` — the local half of the board's WAITING APPROVAL
+  button.** A magic link signs the recipient into the app that MINTED it: the
+  token lives in that app's store, and `return_to` is sanitized to a same-origin
+  PATH. So a link minted by the production task board could only ever land on
+  production — the operator clicked "review this locally" and arrived, signed in,
+  on `mcritchie.studio`. The board now redirects here instead, to the local
+  server named by the task's `local_url`, which mints in its OWN database and
+  lands the operator signed-in on the page under review
+  (`?email=<who>&return_to=<path>`).
+
+  Like the local email inbox it sits beside, this is a developer-desk tool that
+  hands out sign-in material without authenticating anyone, so it is bound to the
+  same floor: the route is drawn outside production only, and every request is
+  re-checked against `Studio.local_tool_enabled?` — production or non-loopback
+  gets a bare 404.
+
+### Changed
+
+- **`Studio.local_tool_enabled?(request_local:)`** — one spelling of the
+  developer-desk floor (not production, loopback only), now shared by
+  `Studio::LocalEmailsController` and `Studio::LocalReviewsController` so a tool
+  added later cannot quietly ship a weaker gate.
+
+- **`Studio::MagicLinkIssuing`** — the mint (`issue_magic_link`) and the URL that
+  consumes it (`magic_link_url_for`) are two halves of one decision
+  (`Studio.magic_link_store`), extracted from `MagicLinksController` and
+  `UserMailer` into a shared concern. Handing out the wrong URL for the store
+  yields "invalid or expired" on a link that was valid; they can no longer drift
+  apart. No behavior change for either existing caller.
+
 ## 0.18.0 — 2026-07-27
 
 ### Added

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # 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.
+  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.
+    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
+    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).
+    def magic_link_url_for(token)
+      Studio.magic_link_via_l_route? ? link_url(token: token) : magic_link_url(token: token)
+    end
+  end
+end

data/app/controllers/magic_links_controller.rb

@@ -15,6 +15,7 @@
 # sign_in_existing / sign_up_new building blocks.
 class MagicLinksController < ApplicationController
   include Studio::LinkConsumption
+  include Studio::MagicLinkIssuing
 
   skip_before_action :require_authentication
   layout false, only: :confirm
@@ -57,18 +58,8 @@ class MagicLinksController < ApplicationController
     redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
   end
 
-  private
-
-  # Mint a token in the configured store. Default :signed keeps the legacy
-  # stateless MessageVerifier link (URL: /magic_link/<token>); :database mints a
-  # Studio::Link row (URL: /l/<token>) — the short, unified scheme. The mailer
-  # builds the matching URL (see UserMailer#magic_link). sign_in_existing /
-  # sign_up_new / safe_path come from Studio::LinkConsumption.
-  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
-  end
+  # issue_magic_link (mint in the configured store) 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/studio/local_emails_controller.rb

@@ -23,7 +23,7 @@ module Studio
     private
 
     def require_local_development!
-      head :not_found if Rails.env.production? || !request.local?
+      head :not_found unless Studio.local_tool_enabled?(request_local: request.local?)
     end
 
     def delivery_records

data/app/controllers/studio/local_reviews_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Studio
+  # GET /_studio/local_review?email=<who>&return_to=<path> — the LOCAL half of
+  # the task board's WAITING APPROVAL button.
+  #
+  # Why it must live here, on the local app. A magic link signs the recipient
+  # into the app that MINTED it: the token is a row (or a signed blob) in that
+  # app's own store, and Studio::LinkToken.sanitize_path keeps `return_to` a
+  # same-origin PATH. So a link minted by the production board can only ever
+  # land on production — no matter what host the path belongs to. The board
+  # therefore stops minting and REDIRECTS here, to the local server named by the
+  # task's local_url, which mints in its own database and lands the operator
+  # signed-in on the page under review.
+  #
+  # It mints for whatever email it is handed, unauthenticated — so it is bound
+  # to the same floor as the local email inbox (Studio::LocalEmailsController):
+  # never in production, and only for a loopback request. That is the same
+  # exposure the inbox already carries, which hands every captured sign-in link
+  # to any local reader. It is a development desk convenience; it is not a
+  # sign-in path.
+  class LocalReviewsController < ApplicationController
+    include Studio::MagicLinkIssuing
+
+    skip_before_action :require_authentication, raise: false
+
+    before_action :require_local_development!
+
+    def show
+      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
+      # 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
+    end
+
+    private
+
+    MISSING_EMAIL = "Add ?email=<your address> to mint a local review link."
+
+    def require_local_development!
+      head :not_found unless Studio.local_tool_enabled?(request_local: request.local?)
+    end
+  end
+end

data/app/mailers/user_mailer.rb

@@ -1,4 +1,10 @@
 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.
+  include Studio::MagicLinkIssuing
+
   # Branded shell (banner + card) for engine-sent UserMailer emails. An app with
   # its own UserMailer + branded_mailer layout (e.g. turf-monster) overrides both.
   layout "branded_mailer"
@@ -18,13 +24,4 @@ class UserMailer < ApplicationMailer
     @banner_alt = "Your #{@app_name} sign-in link"
     mail(to: email, subject: "Your #{@app_name} sign-in link")
   end
-
-  private
-
-  # Match the emailed URL to Studio.magic_link_store: the short /l/<token> for
-  # the :database scheme, the legacy /magic_link/<token> for :signed. The
-  # request side (MagicLinksController#issue_magic_link) mints the matching token.
-  def magic_link_url_for(token)
-    Studio.magic_link_via_l_route? ? link_url(token: token) : magic_link_url(token: token)
-  end
 end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.18.0"
+  VERSION = "0.19.0"
 end

data/lib/studio.rb

@@ -205,6 +205,18 @@ module Studio
     magic_link_store == :database && draw_link_routes
   end
 
+  # The floor every developer-desk tool sits on: the local email inbox
+  # (Studio::LocalEmailsController) and the local-review mint
+  # (Studio::LocalReviewsController). Both hand out sign-in material without
+  # authenticating anyone, so both are OFF in production and OFF for any request
+  # that did not come from the loopback interface. One spelling, so a tool added
+  # later cannot quietly ship a weaker gate. Pass request.local? in.
+  def self.local_tool_enabled?(request_local:)
+    return false if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+
+    !!request_local
+  end
+
   def self.local_email_capture?
     return false if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
     return !!local_email_capture unless local_email_capture.nil?
@@ -299,8 +311,12 @@ module Studio
       get  "auth/:provider/callback", to: "omniauth_callbacks#create"
       get  "auth/failure", to: "omniauth_callbacks#failure"
 
+      # Developer-desk tools. Drawn outside production, and each controller
+      # re-checks Studio.local_tool_enabled? per request (loopback only) — the
+      # route being absent is the outer gate, not the only one.
       unless defined?(Rails) && Rails.env.production?
         get "_studio/local_emails", to: "studio/local_emails#index", as: :studio_local_emails
+        get "_studio/local_review", to: "studio/local_reviews#show",  as: :studio_local_review
       end
 
       # Passwordless email (magic link). Helpers: magic_link_request_path (POST

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -179,6 +178,7 @@ files:
 - app/controllers/concerns/studio/error_handling.rb
 - app/controllers/concerns/studio/impersonation.rb
 - app/controllers/concerns/studio/link_consumption.rb
+- app/controllers/concerns/studio/magic_link_issuing.rb
 - app/controllers/error_logs_controller.rb
 - app/controllers/magic_links_controller.rb
 - app/controllers/navbar_controller.rb
@@ -190,6 +190,7 @@ files:
 - app/controllers/studio/email_images_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
+- app/controllers/studio/local_reviews_controller.rb
 - app/controllers/studio/models_controller.rb
 - app/controllers/style_controller.rb
 - app/controllers/theme_settings_controller.rb
@@ -325,7 +326,6 @@ metadata:
   source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
   bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
   changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -340,8 +340,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching