studio-engine 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f351e5f2cf75e05dfc8befdd34cb525310ab4c4415bb084d15c57a1e3713b782
-  data.tar.gz: f84aad6087299527b4cdb330e644ee707f695b6a70597c753039c8b7af81ee93
+  metadata.gz: bf5f392cf1242e7e541db8ceb7d4ad1865ef2f71f3c787e582de4ac51fc6f836
+  data.tar.gz: 5498dc5d35fbe69c589ba197f3d6fadacbe2d30e93da8b226f0a7d5309ad5ec5
 SHA512:
-  metadata.gz: fc184764831f825771d76f9cc93ae51f0103823c571ad886431beeffeb1ba55c15907004dc1796d6901fdafc560571c02cbde8fdd02141f2629c5cd60071f5a0
-  data.tar.gz: 20a76451338e9aea84191a1c5f3efb995c46514117e18e80d014bda75524ff50e6288abb88da26b84ce463fd296f601e63580de9bfb729458c31cfaf54fa96dc
+  metadata.gz: 3c38ce794988d826bc9f91ad47786f314ea94dfebdfb42164741ffe70379dfb912d3073ac74f61f96a2814157fdcb651293c6d5d3ea9ce9927567d982c153120
+  data.tar.gz: 6046671a635cef22c25af3231d3e562d258ab0fa45ab568d2255d2c734c44d3e27950acd49ead0bda282b17075def27a6ba6c8e35df14807b6df4e2575890d3c

data/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 No entries yet.
 
+## v0.5.4 (2026-06-14)
+
+### Changed
+- Engine magic links are now scanner-safe: emailed links land on an inert GET confirmation page, and the token is consumed only by the CSRF-protected POST from that page.
+- Added the shared `magic_link_consume_path` route helper for consumer apps using engine-drawn auth routes.
+
+## v0.5.3 (2026-06-14)
+
+### Added
+- **`Studio::Email.deliver`** — shared ActionMailer delivery entry point that uses an app-level `EmailDelivery` when present, the engine's namespaced durable outbox when installed, and raw `deliver_later` as a fallback.
+- **`Studio::EmailDelivery` / `Studio::EmailDeliveryJob`** — namespaced durable delivery rows for apps that want shared audit, retry, and resend recovery without colliding with an existing top-level `EmailDelivery` model.
+- **`studio_email_deliveries` migration template** — installable shared outbox table for new or migrating consumer apps.
+
+### Changed
+- Engine magic-link and passwordless signup controllers now send through `Studio::Email.deliver` instead of calling `deliver_later` directly.
+
 ## v0.5.2 (2026-06-13)
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ Shared Rails engine for McRitchie apps. Provides authentication, error handling,
 gem "studio-engine", "~> 0.5"
 ```
 
-Then `bundle install`. The current release is **v0.5.2**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
+Then `bundle install`. The current release is **v0.5.4**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
 
 > Published to RubyGems as of v0.4.0 (2026-05-17). New installs should use the RubyGems form, which the consumer Rails apps (`mcritchie-studio`, `turf-monster`) already use.
 
@@ -62,7 +62,7 @@ Rails.application.routes.draw do
 end
 ```
 
-This draws the enabled auth routes (`/login`, `/signup`, `/logout`, magic-link routes, Solana routes), OAuth callbacks, optional SSO routes, `/error_logs`, and `/admin/theme`.
+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`.
 
 ## Overriding Views
 

data/app/controllers/magic_links_controller.rb

@@ -1,7 +1,8 @@
 # Unified create-or-login email magic link (the passwordless email path).
 #
 #   POST /magic_link        — request a link (email [, return_to])
-#   GET  /magic_link/:token — consume it: log in OR create the account
+#   GET  /magic_link/:token — "Confirm sign-in" interstitial (does NOT consume)
+#   POST /magic_link/:token — consume it: log in OR create the account
 #
 # 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
@@ -14,6 +15,7 @@
 # sign_in_existing / sign_up_new building blocks.
 class MagicLinksController < ApplicationController
   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
@@ -22,7 +24,7 @@ class MagicLinksController < ApplicationController
     email = params[:email].to_s.strip.downcase
     if email.match?(URI::MailTo::EMAIL_REGEXP)
       token = MagicLink.generate(email: email, return_to: safe_path(params[:return_to]))
-      UserMailer.magic_link(email, token).deliver_later
+      Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
     end
     respond_to do |format|
       format.json { render json: { success: true } }
@@ -30,13 +32,22 @@ 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
-    # Keep the token out of Referer headers on the consume page's subresource
-    # loads. Single-use + short TTL is the primary defence; this closes the
-    # passive-leak gap. NOTE: aggressive email link-scanners (Outlook SafeLinks,
-    # Mimecast) may pre-fetch the link and burn the single-use token before the
-    # human clicks — a known magic-link tradeoff; documented for support.
-    response.set_header("Referrer-Policy", "no-referrer")
+    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)

data/app/controllers/registrations_controller.rb

@@ -14,7 +14,7 @@ class RegistrationsController < ApplicationController
       email = (params.dig(:user, :email) || params[:email]).to_s.strip.downcase
       if email.match?(URI::MailTo::EMAIL_REGEXP)
         token = MagicLink.generate(email: email)
-        UserMailer.magic_link(email, token).deliver_later
+        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."
     end

data/app/jobs/studio/email_delivery_job.rb

@@ -0,0 +1,9 @@
+module Studio
+  class EmailDeliveryJob < (defined?(::ApplicationJob) ? ::ApplicationJob : ActiveJob::Base)
+    queue_as :mailers
+
+    def perform(id)
+      Studio::EmailDelivery.find_by(id: id)&.deliver_now!
+    end
+  end
+end

data/app/models/studio/email_delivery.rb

@@ -0,0 +1,46 @@
+module Studio
+  class EmailDelivery < ApplicationRecord
+    self.table_name = "studio_email_deliveries"
+
+    belongs_to :user, optional: true
+
+    scope :unsent, -> { where(sent: false) }
+    scope :recent, -> { order(created_at: :desc) }
+
+    def self.available?
+      connection.data_source_exists?(table_name)
+    rescue ActiveRecord::ActiveRecordError, NoMethodError
+      false
+    end
+
+    def self.deliver(mailer, action, *args, to:, user: nil, **kwargs)
+      record = create!(
+        mailer: mailer.to_s,
+        action: action.to_s,
+        email_key: "#{mailer}##{action}",
+        to: to.to_s,
+        user: user,
+        args: ActiveJob::Arguments.serialize(args),
+        kwargs: ActiveJob::Arguments.serialize([kwargs]).first
+      )
+      Studio::EmailDeliveryJob.perform_later(record.id)
+      record
+    end
+
+    def deliver_now!
+      return if sent?
+
+      pos = ActiveJob::Arguments.deserialize(args)
+      kw = ActiveJob::Arguments.deserialize([kwargs]).first.symbolize_keys
+      mailer.constantize.public_send(action, *pos, **kw).deliver_now
+      update!(sent: true, sent_at: Time.current, error: nil)
+    rescue StandardError => e
+      update(error: e.message.to_s.first(500))
+      raise
+    end
+
+    def self.resend_unsent!
+      unsent.find_each { |delivery| Studio::EmailDeliveryJob.perform_later(delivery.id) }
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <title>Signing you in - <%= Studio.app_name %></title>
+    <style>
+      @keyframes magic-spin { to { transform: rotate(360deg); } }
+
+      * { box-sizing: border-box; }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        color: #f8fafc;
+        background: <%= Studio.theme_dark %>;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+
+      main { width: min(100% - 32px, 420px); text-align: center; }
+
+      .magic-spinner {
+        width: 88px;
+        height: 88px;
+        margin: 0 auto;
+        border-radius: 9999px;
+        border: 8px solid rgba(255, 255, 255, 0.14);
+        border-top-color: <%= Studio.theme_success %>;
+        animation: magic-spin 0.8s linear infinite;
+      }
+
+      .magic-fallback {
+        display: none;
+        margin-top: 2rem;
+        color: rgba(248, 250, 252, 0.8);
+      }
+
+      .magic-fallback p { margin: 0 0 1rem; font-size: 15px; }
+
+      .magic-submit {
+        display: inline-block;
+        max-width: 100%;
+        padding: 14px 34px;
+        border: 0;
+        border-radius: 8px;
+        color: #ffffff;
+        background: <%= Studio.theme_success %>;
+        font: inherit;
+        font-size: 16px;
+        font-weight: 700;
+        cursor: pointer;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="magic-spinner" role="status" aria-label="Signing you in"></div>
+
+      <div id="magic-fallback" class="magic-fallback">
+        <p>Taking longer than expected?</p>
+        <%= button_to magic_link_consume_path(token: @token),
+              method: :post,
+              form: { id: "magic-consume-form", data: { turbo: "false" } },
+              class: "magic-submit" do %>
+          Sign in to <%= Studio.app_name %>
+        <% end %>
+      </div>
+    </main>
+
+    <noscript>
+      <style>
+        #magic-fallback { display: block !important; }
+        .magic-spinner { display: none; }
+      </style>
+    </noscript>
+
+    <script>
+      (function () {
+        var form = document.getElementById("magic-consume-form");
+        if (form && !form.dataset.autoSubmitted) {
+          form.dataset.autoSubmitted = "1";
+          if (typeof form.requestSubmit === "function") form.requestSubmit();
+          else form.submit();
+        }
+
+        setTimeout(function () {
+          var fallback = document.getElementById("magic-fallback");
+          if (fallback) fallback.style.display = "block";
+        }, 4000);
+      })();
+    </script>
+  </body>
+</html>

data/db/migrate/20260614000000_create_studio_email_deliveries.rb

@@ -0,0 +1,22 @@
+class CreateStudioEmailDeliveries < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_email_deliveries do |t|
+      t.string :email_key, null: false
+      t.string :to
+      t.string :mailer, null: false
+      t.string :action, null: false
+      t.jsonb :args, null: false, default: []
+      t.jsonb :kwargs, null: false, default: {}
+      t.boolean :sent, null: false, default: false
+      t.datetime :sent_at
+      t.text :error
+      t.references :user, foreign_key: true
+
+      t.timestamps
+    end
+
+    add_index :studio_email_deliveries, :sent
+    add_index :studio_email_deliveries, :email_key
+    add_index :studio_email_deliveries, :created_at
+  end
+end

data/lib/studio/email.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Studio
+  module Email
+    class << self
+      # Shared email send entry point for Studio apps.
+      #
+      # Apps with an existing top-level EmailDelivery model keep using it through
+      # this facade. Apps that have installed the engine outbox migration use the
+      # namespaced Studio::EmailDelivery model. Apps without either still send via
+      # ActionMailer's normal deliver_later path.
+      def deliver(mailer, action, *args, to:, user: nil, **kwargs)
+        if (adapter = app_delivery_adapter)
+          return adapter.deliver(mailer, action, *args, to: to, user: user, **kwargs)
+        end
+
+        if (adapter = studio_delivery_adapter)
+          return adapter.deliver(mailer, action, *args, to: to, user: user, **kwargs)
+        end
+
+        mailer.public_send(action, *args, **kwargs).deliver_later
+      end
+
+      private
+
+      def app_delivery_adapter
+        return unless Object.const_defined?(:EmailDelivery, false)
+
+        adapter = Object.const_get(:EmailDelivery, false)
+        adapter if adapter.respond_to?(:deliver)
+      rescue NameError
+        nil
+      end
+
+      def studio_delivery_adapter
+        return unless Studio.const_defined?(:EmailDelivery, false)
+
+        adapter = Studio.const_get(:EmailDelivery, false)
+        adapter if adapter.respond_to?(:available?) && adapter.available?
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.5.2"
+  VERSION = "0.5.4"
 end

data/lib/studio.rb

@@ -5,6 +5,7 @@ require "studio/theme_resolver"
 require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
+require "studio/email"
 require "studio/mail_transport"
 
 module Studio
@@ -37,7 +38,7 @@ module Studio
   mattr_accessor :draw_auth_routes, default: true
 
   # Default From: for engine-sent mail (magic links). Apps set this to their
-  # verified Resend sending address in config/initializers/studio.rb.
+  # verified sending address in config/initializers/studio.rb.
   mattr_accessor :mailer_from, default: nil
 
   # Theme role colors (7 roles)
@@ -158,12 +159,16 @@ module Studio
       get  "auth/failure", to: "omniauth_callbacks#failure"
 
       # Passwordless email (magic link). Helpers: magic_link_request_path (POST
-      # to request a link) + magic_link_path(token) / magic_link_url(token:)
-      # (the emailed consume link). The token is a URL-safe MessageVerifier blob
-      # but the constraint guards against a stray "." segment.
+      # 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.
       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#consume", as: :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{[^/]+} }
       end
 

data/studio-engine.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
     "changelog_uri"   => "https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md"
   }
 
-  spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE"]
+  spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "db/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE"]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "rails", ">= 7.0", "< 8.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.4
 platform: ruby
 authors:
 - Alex McRitchie
@@ -153,6 +153,7 @@ files:
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
+- app/jobs/studio/email_delivery_job.rb
 - app/mailers/application_mailer.rb
 - app/mailers/user_mailer.rb
 - app/models/concerns/sluggable.rb
@@ -160,6 +161,7 @@ files:
 - app/models/error_log.rb
 - app/models/image_cache.rb
 - app/models/session_context.rb
+- app/models/studio/email_delivery.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
 - app/services/magic_link.rb
@@ -182,6 +184,7 @@ files:
 - app/views/layouts/_navbar.html.erb
 - app/views/layouts/studio/_flash.html.erb
 - app/views/layouts/studio/_head.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
@@ -199,9 +202,11 @@ files:
 - app/views/theme_settings/edit.html.erb
 - app/views/user_mailer/magic_link.html.erb
 - app/views/user_mailer/magic_link.text.erb
+- db/migrate/20260614000000_create_studio_email_deliveries.rb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/color_scale.rb
+- lib/studio/email.rb
 - lib/studio/engine.rb
 - lib/studio/image_cache.rb
 - lib/studio/mail_transport.rb