studio-engine 0.117.0 → 0.119.0

data/app/views/studio/google_sign_in/_setup_modal.html.erb

@@ -0,0 +1,55 @@
+<%# The Google setup modal, opened by studio/google_sign_in/_button while the
+    app has no OAuth client. One root element: the host's template x-if clones
+    only the first. No double quote inside any x-data or @click below.
+
+    Locals:
+      email_fallback — true: "Use email instead" closes the modal and focuses
+                       the page's email field. false: "Not now" only closes it.
+                       The focus waits out the close: the host hands focus
+                       back to the opener when its last card leaves (220ms,
+                       CLOSE_ANIM_MS), which would otherwise undo it.
+
+    "Request Google setup" is a plain form POST with Turbo off, so it works with
+    the same CSRF token as every other engine form, and the flash on the page it
+    lands back on says what happened. Hidden when the host draws its own routes
+    without Studio.routes, which leaves nowhere to send it. %>
+<%
+  setup_email_fallback = local_assigns.fetch(:email_fallback, true)
+  setup_request_path = respond_to?(:studio_google_setup_request_path) ? studio_google_setup_request_path : nil
+%>
+<div class="text-center" data-google-setup-modal>
+  <div class="flex justify-end -mt-2 -mr-2">
+    <button type="button" @click="$store.googleSetupModals.close()"
+            class="text-secondary hover:text-heading text-xl leading-none"
+            aria-label="Close">&times;</button>
+  </div>
+
+  <div class="mx-auto mb-4 w-12 h-12 rounded-full bg-white border border-subtle shadow-sm flex items-center justify-center">
+    <%= render "components/google_logo" %>
+  </div>
+
+  <h3 class="text-heading font-bold text-lg leading-tight">Google sign-in is almost ready</h3>
+  <p class="text-secondary text-sm mt-2">
+    Google sign-in is still being set up for <%= Studio.app_name %>.
+    <% if setup_request_path %>Ask the team to finish it, and<% else %>Until it is,<% end %>
+    <% if setup_email_fallback %>sign in with your email in the meantime.<% else %>use another sign-in method in the meantime.<% end %>
+  </p>
+
+  <div class="mt-6 flex flex-col gap-3">
+    <% if setup_request_path %>
+      <%= button_to "Request Google setup", setup_request_path, method: :post,
+            data: { turbo: false }, class: "btn btn-primary w-full", form: { class: "w-full" } %>
+    <% end %>
+
+    <% if setup_email_fallback %>
+      <button type="button" class="btn btn-neutral w-full"
+              @click="$store.googleSetupModals.close(); setTimeout(() => document.querySelector('input[type=email]')?.focus(), 260)">
+        Use email instead
+      </button>
+    <% else %>
+      <button type="button" class="btn btn-neutral w-full" @click="$store.googleSetupModals.close()">
+        Not now
+      </button>
+    <% end %>
+  </div>
+</div>

data/app/views/studio/loader/_loader.html.erb

@@ -0,0 +1,75 @@
+<%# locals: (style:, size:, icon:, art:, label:, percent:, mono:, pending:, uid:, html: {}) %>
+<%#
+  The branded loader (Studio::LoaderHelper#studio_loader, docs/LOADER.md): ONE
+  class, .studio-loader, sized by --studio-loader-size, styled per
+  data-loader-style by engine-motion.css (section "Branded loader"). The icon is
+  the app's own file; a signature style inlines the art's marked layers over it.
+
+  A pending loader sits inside a button: hidden from assistive tech (the button
+  carries aria-busy) and from sight until the button or its form is busy.
+%>
+<%
+  extra = html.dup
+  data = (extra.delete(:data) || {}).merge(loader_style: style.to_s.tr("_", "-"))
+  data[:loader_pending] = "" if pending
+  data[:loader_mono] = "" if mono
+  data[:loader_percent] = "" unless percent.nil?
+  vars = [ "--studio-loader-size: #{size}" ]
+  vars << "--studio-loader-percent: #{percent}" unless percent.nil?
+  vars << extra.delete(:style) if extra[:style]
+  classes = [ "studio-loader", extra.delete(:class) ].compact.join(" ")
+  draw_icon = lambda do |modifier = nil|
+    css = [ "studio-loader-icon", modifier ].compact.join(" ")
+    if icon.blank?
+      tag.span(class: css, data: { loader_blank: "" })
+    elsif mono
+      tag.span(class: css, style: "--studio-loader-mask: url(\"#{icon.to_s.gsub('"', '%22')}\")")
+    else
+      tag.img(src: icon, alt: "", class: css, draggable: "false", decoding: "async")
+    end
+  end
+  aria = pending ? { hidden: "true" } : { live: "polite" }
+%>
+<%= tag.span(class: classes, role: (pending ? nil : "status"), aria: aria, data: data, style: vars.join("; "), **extra) do %>
+  <% case style %>
+  <% when :breathe %>
+    <span class="studio-loader-halo" aria-hidden="true"></span>
+    <%= draw_icon.call %>
+  <% when :liquid %>
+    <%= draw_icon.call("studio-loader-ghost") %>
+    <span class="studio-loader-fill" aria-hidden="true"><%= draw_icon.call %></span>
+  <% when :orbit %>
+    <span class="studio-loader-track" aria-hidden="true"></span>
+    <%= draw_icon.call %>
+    <span class="studio-loader-orb" aria-hidden="true"><span class="studio-loader-trail"></span><span class="studio-loader-spark"></span></span>
+  <% when :steel %>
+    <svg class="studio-loader-frame" viewBox="0 0 100 100" aria-hidden="true"><path d="M0,14V0H14M86,0H100V14M100,86V100H86M14,100H0V86"/></svg>
+    <%= draw_icon.call %>
+  <% when :weld_bead %>
+    <%= draw_icon.call %>
+    <svg class="studio-loader-art" viewBox="<%= art[:view_box] %>" aria-hidden="true">
+      <defs><filter id="<%= uid %>-glow" x="-20%" y="-20%" width="140%" height="140%"><feGaussianBlur stdDeviation="<%= (art[:width] / 52.86).round(2) %>" result="b"/><feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge></filter></defs>
+      <% outline = art[:layers].first %>
+      <% layers = studio_loader_bead_layers(art) %>
+      <% [ layers.reject { |l| l[:glow] }, layers.select { |l| l[:glow] } ].each_with_index do |group, glowing| %>
+        <%= tag.g(filter: (glowing == 1 ? "url(##{uid}-glow)" : nil), transform: outline[:transform]) do %>
+          <% group.each do |layer| %>
+            <%= tag.path(d: outline[:d], pathLength: "100", class: "studio-loader-bead", data: { layer: layer[:n] },
+                         "stroke-width": layer[:width], "stroke-opacity": layer[:opacity],
+                         "stroke-dasharray": "#{layer[:dash]} #{(100 - layer[:dash]).round(2)}",
+                         style: "--studio-loader-bead-length: #{layer[:dash]}") %>
+          <% end %>
+        <% end %>
+      <% end %>
+    </svg>
+  <% when :sparkle %>
+    <%= draw_icon.call %>
+    <svg class="studio-loader-art" viewBox="<%= art[:view_box] %>" aria-hidden="true">
+      <% art[:layers].each_with_index do |spark, index| %>
+        <%= tag.path(d: spark[:d], transform: spark[:transform], class: "studio-loader-sparkle",
+                     style: "--studio-loader-i: #{index}; --studio-loader-sparks: #{art[:layers].size}") %>
+      <% end %>
+    </svg>
+  <% end %>
+  <% unless pending || label.blank? %><span class="sr-only"><%= label %></span><% end %>
+<% end %>

data/app/views/studio/loader/_overlay.html.erb

@@ -0,0 +1,16 @@
+<%# locals: (label:, delay:, max_wait:, size:, options: {}) %>
+<%#
+  The page-load overlay (Studio::LoaderHelper#studio_loader_overlay). Rendered
+  hidden, once per page; studio/loader shows it when a visit the user started
+  or a form marked data-studio-loader-overlay outlasts data-delay ms, clears it
+  after data-max-wait ms at most, and window.StudioLoader.show(caption) /
+  hide() drive it for any other long wait. The caption line is empty until a
+  caller names one. It never marks itself aria-busy: that would mute the
+  "Loading" status inside it.
+%>
+<%= tag.div(class: "studio-loader-overlay", hidden: true, data: { studio_loader_overlay: "", delay: delay, max_wait: max_wait }) do %>
+  <div class="studio-loader-overlay-panel">
+    <%= studio_loader(size: size, label: label, **options) %>
+    <p class="studio-loader-caption" data-studio-loader-caption></p>
+  </div>
+<% end %>

data/app/views/studio/profiles/_google_section.html.erb

@@ -48,9 +48,9 @@
     <% end %>
   </div>
 <% else %>
-  <%= button_to "/auth/google_oauth2", method: :post, data: { turbo: false },
-                class: "btn btn-google gap-3 w-full" do %>
-    <%= render "components/google_logo" %>
-    Link Google Account
-  <% end %>
+  <%# A POST to OmniAuth once the app has its OAuth client, the setup modal
+      until then (studio/google_sign_in/_button). Already signed in, so the
+      modal offers "Not now" rather than a way back to email. %>
+  <%= render "studio/google_sign_in/button", label: "Link Google Account",
+             button_class: "btn btn-google gap-3 w-full", email_fallback: false %>
 <% end %>

data/app/views/style/_tricks.html.erb

@@ -185,6 +185,65 @@
     </div>
   </section>
 
+  <!-- Branded loader -->
+  <%
+    loader_config = Studio.loader
+    # An ERB tag as text, built so this file never holds a closing tag inside one.
+    erb_tag = ->(code) { "<" + "%= #{code} %" + ">" }
+    loader_art_styles = Studio::Loader::ART_STYLES.keys.select do |style|
+      loader_config[:art] && Studio::Loader.art(loader_config[:art], style)
+    end
+  %>
+  <section id="loader" class="space-y-5" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+    <div class="space-y-1">
+      <h3 class="text-xl font-bold text-heading">Branded loader</h3>
+      <p class="text-muted text-sm max-w-2xl">
+        This app's own icon in its theme colours, in the style <code class="font-mono text-2xs">config.loader</code>
+        names (<strong><%= loader_config[:style].to_s.tr("_", " ") %></strong>). Page loads, long waits and pending
+        buttons all draw it. One class, <code class="font-mono text-2xs">.studio-loader</code>, sized by
+        <code class="font-mono text-2xs">--studio-loader-size</code>. studio-engine docs/LOADER.md.
+      </p>
+    </div>
+    <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+      <%= render layout: "style/specimen",
+            locals: { klass: ".studio-loader (this app's style)",
+                      usage: [erb_tag.call("studio_loader"), erb_tag.call('studio_loader size: 20, label: "Saving"')].join("\n") } do %>
+        <%= studio_loader %>
+        <%= studio_loader size: 32 %>
+        <%= studio_loader size: 20 %>
+      <% end %>
+
+      <%= render layout: "style/specimen",
+            locals: { klass: "studio_loader_pending (inside a busy button)",
+                      usage: ["<button class=\"btn btn-primary\">", "  <span data-loader-idle>Save</span>", "  #{erb_tag.call('studio_loader_pending')}", "</button>"].join("\n") } do %>
+        <button type="button" class="btn btn-primary" aria-busy="true">
+          <%= studio_loader_pending %><span class="ml-2">Saving…</span>
+        </button>
+      <% end %>
+
+      <%= render layout: "style/specimen",
+            locals: { klass: "studio_loader_overlay (the page-load overlay)",
+                      usage: ["#{erb_tag.call('studio_loader_overlay')}  (once, in the layout body)", 'window.StudioLoader.show("Caption") / .hide()'].join("\n") } do %>
+        <button type="button" class="btn btn-secondary" data-test="style-show-loader-overlay"
+                x-data x-on:click="window.StudioLoader && window.StudioLoader.show('Loading your page…'); setTimeout(() => window.StudioLoader && window.StudioLoader.hide(), 3000)">
+          Show the overlay for 3 seconds
+        </button>
+      <% end %>
+
+      <% Studio::Loader::STYLES.each do |style| %>
+        <% signature = Studio::Loader.art_style?(style) %>
+        <% unavailable = signature && !loader_art_styles.include?(style) %>
+        <%= render layout: "style/specimen",
+              locals: { klass: %(style: :#{style}#{signature ? " (signature, needs art)" : ""}),
+                        usage: %(config.loader = #{signature ? "{ style: :#{style}, art: \"/brand/loader-#{style}.svg\" }" : ":#{style}"}),
+                        disabled: unavailable, disabled_label: "needs this app's art file" } do %>
+          <%= studio_loader style: style, size: 72 %>
+          <%= studio_loader style: style, size: 28 %>
+        <% end %>
+      <% end %>
+    </div>
+  </section>
+
   <!-- Motion primitives -->
   <section class="space-y-5">
     <div class="space-y-1">

data/lib/studio/engine.rb

@@ -11,6 +11,15 @@ require_relative "component_gallery"
 # the order this file saw; out of order, the gallery is not mounted.
 Studio::ComponentGallery.lookbook_loaded_before_engine = defined?(::Lookbook::Engine) ? true : false
 require "view_component"
+# Google sign-in ships ready (Studio::GoogleSignIn): the strategy, and the CSRF
+# check on its POST-only request phase. Required here because Bundler.require
+# loads only the gems a host's Gemfile names, and a new app names none of these.
+# The CSRF gem registers a Railtie, so it has to load before the app initializes,
+# which a require at engine load does. Idempotent beside a host's own require.
+require "omniauth"
+require "omniauth-google-oauth2"
+require "omniauth/rails_csrf_protection"
+require_relative "google_sign_in"
 
 module Studio
   class Engine < ::Rails::Engine
@@ -274,6 +283,22 @@ module Studio
             .sort
     end
 
+    # GOOGLE SIGN-IN, the engine's registration (Studio::GoogleSignIn). The
+    # middleware is added to every host and decides per request whether it is
+    # the google_oauth2 strategy or a pass-through: a host whose own
+    # config/initializers/omniauth.rb registers google_oauth2 keeps its own, and
+    # the engine never registers a second. It cannot decide here, because the
+    # host's initializers have not run yet. `use` appends, and this runs before
+    # the host's initializers, so the engine's middleware sits outside the
+    # host's OmniAuth::Builder and hands the request on to it.
+    #
+    # The request phase is POST-only by OmniAuth 2's own default
+    # (allowed_request_methods [:post]), and omniauth-rails_csrf_protection
+    # checks the token on it; nothing here changes either.
+    initializer "studio.google_sign_in" do |app|
+      app.config.middleware.use Studio::GoogleSignIn::Middleware
+    end
+
     initializer "studio.footer_only_eager_load" do
       next if Studio.active_record?
 

data/lib/studio/google_sign_in.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module Studio
+  # Google sign-in that ships ready with every app (docs/GOOGLE_AUTH_SETUP.md).
+  #
+  # Alex McRitchie, 2026-10-29: "I want this to be automatic with new apps. Even
+  # if there is still manual work to be done, please have the link for google
+  # login. If there is manual work to be done to properly setup Google, the link
+  # should show a modal requesting access to Google auth."
+  #
+  # So an app that bundles studio-engine gets, with nothing of its own:
+  #
+  #   * the google_oauth2 OmniAuth strategy, registered by the engine's
+  #     Middleware below, UNLESS the host's own initializer registered one;
+  #   * a default User.from_omniauth (Studio::OmniauthUser), which a host's own
+  #     definition overrides;
+  #   * the "Sign in with Google" button on /login, /signup and /profile. While
+  #     the OAuth client is not configured (ready? false) the button opens a
+  #     modal that asks the team to finish setup, instead of posting to a
+  #     strategy that would send the person to a Google error page.
+  #
+  # THE ONE MANUAL STEP that cannot ship in a gem: register the app's callback
+  # (redirect_uri below) on the shared production OAuth client and set
+  # GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. The modal's "Request Google setup"
+  # mails the team exactly that.
+  #
+  # Pure Ruby apart from the methods that read Rails.application or OmniAuth,
+  # each of which guards on the constant, so the unit suite loads this file as is.
+  module GoogleSignIn
+    PROVIDER      = "google_oauth2"
+    REQUEST_PATH  = "/auth/google_oauth2"
+    CALLBACK_PATH = "/auth/google_oauth2/callback"
+    SCOPE         = "email,profile"
+    PROMPT        = "select_account"
+    CREDENTIAL_KEYS = %w[GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET].freeze
+
+    # How long a "Request Google setup" claim holds. The key is per day, so this
+    # only has to outlive the day it names.
+    REQUEST_TTL_SECONDS = 26 * 60 * 60
+
+    # Records what an OmniAuth::Builder block registers without registering
+    # anything: `provider` notes its first argument, and every other call a
+    # host's block makes (configure, on_failure, options) is swallowed.
+    class ProviderRecorder
+      attr_reader :providers
+
+      def initialize
+        @providers = []
+      end
+
+      def provider(klass, *_args, **_options, &_block)
+        @providers << klass
+        nil
+      end
+
+      def method_missing(*_args, **_options, &_block)
+        nil
+      end
+
+      def respond_to_missing?(*_args)
+        true
+      end
+    end
+
+    # The engine's half of the registration: a Rack middleware the engine adds
+    # to every host's stack (Studio::Engine, "studio.google_sign_in"). It is the
+    # google_oauth2 strategy when the engine owns Google, and a pass-through
+    # otherwise:
+    #
+    #   * the host registered its own provider  -> pass through; the host's wins
+    #   * no credentials and not OmniAuth test mode -> pass through, so POST
+    #     /auth/google_oauth2 answers 404 rather than a Google error page
+    #   * otherwise -> the strategy, built from the credentials of the moment
+    #
+    # Deciding per request rather than at boot is what makes host detection
+    # possible: the engine's initializers run BEFORE the host's
+    # config/initializers, so at boot the host's OmniAuth::Builder is not yet on
+    # the stack to be seen.
+    class Middleware
+      def initialize(app)
+        @app = app
+        @strategies = {}
+        @lock = Mutex.new
+      end
+
+      def call(env)
+        return @app.call(env) unless GoogleSignIn.engine_registers?
+
+        strategy(*GoogleSignIn.credentials).call(env)
+      end
+
+      private
+
+      # The strategy's callback host is pinned when the app names one (see
+      # GoogleSignIn.pinned_full_host), and otherwise OmniAuth's allowed_hosts
+      # is seeded from config.hosts (GoogleSignIn.seed_allowed_hosts!), so a
+      # forged Host or X-Forwarded-Host never becomes the redirect_uri Google
+      # sees. Either one also settles OmniAuth 2.3's request-host warning.
+      def strategy(client_id, client_secret)
+        @lock.synchronize do
+          @strategies[[client_id, client_secret]] ||= begin
+            options = { scope: SCOPE, prompt: PROMPT }
+            if (full_host = GoogleSignIn.pinned_full_host)
+              options[:full_host] = full_host
+            else
+              GoogleSignIn.seed_allowed_hosts!
+            end
+            ::OmniAuth::Strategies::GoogleOauth2.new(@app, client_id, client_secret, **options)
+          end
+        end
+      end
+    end
+
+    class << self
+      # True when the app holds an OAuth client: both env vars present.
+      def ready?(env: ENV)
+        CREDENTIAL_KEYS.all? { |key| !env[key].to_s.strip.empty? }
+      end
+
+      def credentials(env: ENV)
+        CREDENTIAL_KEYS.map { |key| env[key].to_s.strip.then { |value| value.empty? ? nil : value } }
+      end
+
+      # OmniAuth's test mode answers every request with the mock, so the button
+      # posts there whatever the credentials say.
+      def mock_mode?
+        defined?(::OmniAuth) && ::OmniAuth.config.test_mode ? true : false
+      end
+
+      # Whether the Google button POSTs to the strategy (true) or opens the
+      # setup modal (false). A host that registered its own provider owns its
+      # readiness, so its button keeps posting exactly as it did before the
+      # engine shipped one: hub, turf-monster, moms-app, cyvasse and
+      # acquisition-studio test their buttons as POST forms with no credentials.
+      def button_posts?(env: ENV)
+        ready?(env: env) || mock_mode? || host_registered?
+      end
+
+      # Whether the engine's own strategy answers /auth/google_oauth2.
+      def engine_registers?(env: ENV)
+        return false if host_registered?
+
+        ready?(env: env) || mock_mode?
+      end
+
+      # :host, :engine or :none: who answers /auth/google_oauth2 right now.
+      def registration(env: ENV)
+        return :host if host_registered?
+
+        engine_registers?(env: env) ? :engine : :none
+      end
+
+      # The callback a Google OAuth client must list for this host.
+      def redirect_uri(host:, scheme: "https")
+        "#{scheme}://#{host}#{CALLBACK_PATH}"
+      end
+
+      # ---- The app's canonical host: from configuration, NEVER the request ----
+      #
+      # "Request Google setup" mails ops a redirect URI to add to the shared
+      # production OAuth client, so that URI must not come from a header a
+      # stranger controls (Host, X-Forwarded-Host). In order:
+      #
+      #   1. Studio.google_canonical_host, set in config/initializers/studio.rb
+      #   2. ENV["APP_HOST"], the deployed apps' canonical host (the hub's
+      #      CanonicalHost reads the same variable)
+      #   3. the first config.hosts entry that is a plain hostname: a String of
+      #      letters, digits, dots and hyphens, no port, no leading dot
+      #
+      # nil when none is configured; the email then says so instead of naming
+      # a host.
+      PLAIN_HOSTNAME = /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\z/i
+
+      def canonical_host(env: ENV, configured: configured_canonical_host, hosts: rails_config_hosts)
+        explicit = normalize_host(configured) || normalize_host(env["APP_HOST"])
+        return explicit if explicit
+
+        Array(hosts).find { |entry| entry.is_a?(String) && PLAIN_HOSTNAME.match?(entry) }&.downcase
+      end
+
+      # Scheme and host only, lowercased: "https://App.Example/x" -> "app.example".
+      # A port an operator wrote into APP_HOST is kept; it is configuration.
+      def normalize_host(value)
+        text = value.to_s.strip.sub(%r{\A[a-z][a-z0-9+.-]*://}i, "").split("/").first.to_s.downcase
+        text.empty? ? nil : text
+      end
+
+      def canonical_scheme(production: rails_production?)
+        production ? "https" : "http"
+      end
+
+      # The redirect URI to register, from the canonical host; nil when the app
+      # names none.
+      def canonical_redirect_uri(env: ENV, production: rails_production?)
+        host = canonical_host(env: env)
+        host && redirect_uri(host: host, scheme: canonical_scheme(production: production))
+      end
+
+      # The strategy's full_host: pinned only in production and only from an
+      # EXPLICIT host (Studio.google_canonical_host or APP_HOST). A desk on
+      # localhost:<port> must keep its own port in the callback, and a QA app's
+      # config.hosts may list the production host first.
+      def pinned_full_host(env: ENV, production: rails_production?)
+        return nil unless production
+
+        host = normalize_host(configured_canonical_host) || normalize_host(env["APP_HOST"])
+        host && "https://#{host}"
+      end
+
+      # OmniAuth.config.allowed_hosts mirrored from config.hosts, so OmniAuth
+      # builds callbacks only on hosts the app already accepts. Left alone when
+      # the app set OmniAuth's own host config, when config.hosts is empty, or
+      # when it admits every host anyway (an IPAddr range, as development has).
+      # A leading-dot entry (".example.com") becomes the same subdomain pattern
+      # Rails gives it; ports are dropped, since OmniAuth compares bare hosts.
+      def allowed_hosts_from(hosts)
+        entries = Array(hosts)
+        return nil if entries.empty?
+        return nil if entries.any? { |entry| !entry.is_a?(String) && !entry.is_a?(Regexp) }
+
+        entries.map do |entry|
+          next entry if entry.is_a?(Regexp)
+
+          bare = entry.downcase.sub(/:\d+\z/, "")
+          bare.start_with?(".") ? /(?:[a-z0-9-]+\.)*#{Regexp.escape(bare.delete_prefix("."))}/i : bare
+        end.uniq
+      end
+
+      def seed_allowed_hosts!(hosts: rails_config_hosts)
+        return unless defined?(::OmniAuth)
+        return if ::OmniAuth.config.full_host || ::OmniAuth.config.allowed_hosts
+
+        allowed = allowed_hosts_from(hosts)
+        ::OmniAuth.config.allowed_hosts = allowed if allowed
+      end
+
+      # The once-a-day key: the app, not the request's host, so a forged Host or
+      # port cannot mint a fresh day.
+      def app_key
+        name = defined?(Studio) && Studio.respond_to?(:app_name) ? Studio.app_name.to_s : ""
+        key = name.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-").delete_suffix("-")
+        key.empty? ? "app" : key
+      end
+
+      # Does a built middleware stack already register google_oauth2? Reads each
+      # entry's class and block (ActionDispatch::MiddlewareStack::Middleware):
+      #
+      #   * the strategy used directly (`use OmniAuth::Strategies::GoogleOauth2`)
+      #   * an OmniAuth::Builder whose block calls `provider :google_oauth2`,
+      #     found by evaluating the block against a ProviderRecorder
+      #
+      # A Builder registering only other providers does not count, so the engine
+      # still supplies Google beside them. A block the recorder cannot evaluate
+      # counts as registering Google: two strategies on one path is the failure
+      # this exists to prevent, so doubt resolves toward the host.
+      def host_registers_google?(middlewares)
+        Array(middlewares).any? do |entry|
+          klass = entry.respond_to?(:klass) ? entry.klass : entry
+          name = klass.to_s
+          next false if name == Middleware.name
+          next true if google_provider?(klass)
+          next false unless omniauth_builder?(klass)
+
+          builder_registers_google?(entry.respond_to?(:block) ? entry.block : nil)
+        end
+      end
+
+      def builder_registers_google?(block)
+        return false unless block
+
+        recorder = ProviderRecorder.new
+        recorder.instance_eval(&block)
+        recorder.providers.any? { |provider| google_provider?(provider) }
+      rescue StandardError, ScriptError
+        true
+      end
+
+      def google_provider?(provider)
+        name = provider.to_s
+        name == PROVIDER || name.end_with?("::GoogleOauth2")
+      end
+
+      def omniauth_builder?(klass)
+        return true if klass.to_s == "OmniAuth::Builder"
+
+        defined?(::OmniAuth::Builder) && klass.is_a?(Class) && klass < ::OmniAuth::Builder ? true : false
+      end
+
+      # Memoized once the app's stack is built; nil-safe before that (and in a
+      # process with no Rails app), answering false without memoizing.
+      def host_registered?
+        return @host_registered unless @host_registered.nil?
+
+        stack = rails_middleware_stack
+        return false unless stack
+
+        @host_registered = host_registers_google?(stack.middlewares)
+      end
+
+      def reset!
+        @host_registered = nil
+        @fallback_store = nil
+      end
+
+      # "Request Google setup" is answered once per APP per day (key: app_key,
+      # never a request header). Returns true for the request that claims the
+      # day, false for every later one.
+      #
+      # Checked with exist? before the unless_exist write, because not every
+      # cache store honours unless_exist; the two together leave only a race
+      # between simultaneous first clicks, which costs one extra email.
+      def claim_daily_request(app = app_key, store: request_store, today: current_date)
+        key = "studio/google_setup_request/#{app.to_s.downcase}/#{today.iso8601}"
+        return false if store.exist?(key)
+
+        store.write(key, today.iso8601, unless_exist: true, expires_in: REQUEST_TTL_SECONDS) ? true : false
+      end
+
+      # The app's Rails.cache, unless that is a NullStore, which remembers
+      # nothing and would let every click mail the team. Then a store of this
+      # process's own: a per-dyno limit, still a limit.
+      def request_store
+        cache = defined?(::Rails) && ::Rails.respond_to?(:cache) ? ::Rails.cache : nil
+        return cache if cache && !(defined?(::ActiveSupport::Cache::NullStore) && cache.is_a?(::ActiveSupport::Cache::NullStore))
+
+        @fallback_store ||= begin
+          require "active_support/cache"
+          ::ActiveSupport::Cache::MemoryStore.new
+        end
+      end
+
+      # The app's day (Time.zone) where ActiveSupport has one, else the system's.
+      def current_date
+        Date.respond_to?(:current) ? Date.current : Date.today
+      end
+
+      private
+
+      def configured_canonical_host
+        defined?(Studio) && Studio.respond_to?(:google_canonical_host) ? Studio.google_canonical_host : nil
+      end
+
+      def rails_config_hosts
+        return [] unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        Array(::Rails.application.config.hosts)
+      end
+
+      def rails_production?
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.production? ? true : false
+      end
+
+      def rails_middleware_stack
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        stack = ::Rails.application.config.middleware
+        stack.respond_to?(:middlewares) ? stack : nil
+      end
+    end
+  end
+end