studio-engine 0.56.4 → 0.57.1

data/app/controllers/studio/geo_settings_controller.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Studio
+  # /admin/geo — the shared geo manager, plus /geo/check, the probe that reports
+  # what the server thinks of THIS visitor.
+  #
+  # A plain host-inherited controller whose view is a bare content wrapper, like
+  # /admin/emails and /admin/style, so it renders inside each host's application
+  # layout and picks up that app's navbar and theme.
+  #
+  # Three things an operator can do here, and each exists because doing it any
+  # other way means a deploy:
+  #
+  #   1. turn the gate on or off — the kill switch;
+  #   2. edit the blocked list — countries, and subdivisions of the home country;
+  #   3. SIMULATE a blocked location, so the blocked experience can be walked
+  #      from a desk without a VPN.
+  #
+  # Routes are opt-in (Studio.draw_geo_routes) because turf-monster owns these
+  # exact helper names until its adoption lands. See Studio.routes.
+  class GeoSettingsController < ApplicationController
+    # This page ASKS the questions the concern answers — where is this visitor,
+    # are they blocked, are they simulating — so it includes the concern rather
+    # than assuming the host's ApplicationController did. A host that already
+    # includes it loses nothing: Rails' callback chain de-duplicates a repeated
+    # `before_action :detect_geo_state`, so detection still runs once.
+    include Studio::GeoDetection
+
+    # The probe is PUBLIC — a page's own JavaScript asks it whether this visitor
+    # is blocked, and that question has to be answerable before sign-in.
+    skip_before_action :require_authentication, only: :check, raise: false
+    before_action :require_admin, except: :check
+
+    # GET /geo/check — force a fresh detection and report the verdict.
+    #
+    # Forcing is the point: an operator moving between networks needs an answer
+    # about where they are NOW, not the one cached for the next day. A simulated
+    # location is left alone, or the probe would silently cancel the simulation
+    # it is supposed to describe.
+    def check
+      unless geo_override_active?
+        reset_geo_detection!
+        detect_geo_state
+      end
+
+      render json: {
+        country: geo_country,
+        subdivision: geo_state,
+        region: geo_region_token,
+        simulated: geo_override_active?,
+        blocked: geo_blocked?,
+        # The legacy key turf-monster's client already reads. Kept so an app can
+        # adopt this endpoint without shipping a JavaScript change on the same day.
+        state: geo_state
+      }
+    end
+
+    TABS = %w[states countries].freeze
+
+    def edit
+      @geo_setting = Studio::GeoSetting.current
+      # Which editor is open. It rides in the URL so a save can send the operator
+      # back to the one they were working in rather than resetting to states.
+      @tab = TABS.include?(params[:tab]) ? params[:tab] : "states"
+      # Where the simulate button would put you. The page NAMES it — "Simulate
+      # WA" beats "Simulate a blocked location", because the operator is about to
+      # be moved and should read where to.
+      @simulated_region = simulated_region
+    end
+
+    def update
+      @geo_setting = Studio::GeoSetting.current
+
+      @geo_setting.enabled = ActiveModel::Type::Boolean.new.cast(params.dig(:geo_setting, :enabled))
+      @geo_setting.banned_subdivisions = submitted_subdivisions
+      @geo_setting.banned_countries = submitted_countries
+      @geo_setting.save!
+
+      redirect_to admin_geo_path(tab: submitted_tab), notice: "Geo settings updated."
+    rescue StandardError => e
+      redirect_to admin_geo_path(tab: submitted_tab), alert: "Failed to update: #{e.message}"
+    end
+
+    # POST /admin/geo/toggle — stand in a blocked location, or stop.
+    def toggle_override
+      if geo_override_active?
+        session.delete(:geo_override)
+        return redirect_back fallback_location: admin_geo_path, notice: "Geo simulation cleared."
+      end
+
+      region = simulated_region
+      # Nothing is blocked yet, so there is no blocked experience to walk. Say
+      # that plainly instead of pinning the operator to a location that behaves
+      # exactly like the one they are already in.
+      if region.nil?
+        return redirect_back fallback_location: admin_geo_path,
+                             alert: "Nothing is blocked yet — add a country or a state first."
+      end
+
+      session[:geo_override] = region
+      redirect_back fallback_location: admin_geo_path, notice: "Simulating #{place_name(region)}."
+    end
+
+    private
+
+    # The page posts this list three different ways: a checkbox grid posts bare
+    # codes one per box ("WA"), a text field posts one comma-separated string
+    # ("CA-AB, MX-BC"), and the grid's hidden anchor posts a blank so that
+    # unchecking the LAST box still submits an empty list rather than nothing.
+    # Split and flatten all three into plain entries here; the model decides what
+    # each entry means.
+    def submitted_subdivisions
+      split_list(params.dig(:geo_setting, :banned_subdivisions))
+    end
+
+    def submitted_countries
+      split_list(params.dig(:geo_setting, :banned_countries))
+    end
+
+    # The tab radio posts with the form, so "save" lands back where the operator
+    # was. Whitelisted rather than echoed: this value goes into a redirect URL.
+    def submitted_tab
+      TABS.include?(params[:tab]) ? params[:tab] : nil
+    end
+
+    def split_list(raw)
+      Array(raw).flat_map { |value| value.to_s.split(/[\s,]+/) }.reject(&:blank?)
+    end
+
+    # WHERE the simulator stands. The app's configured choice wins; otherwise the
+    # first region this app actually blocks, which is the one worth walking. With
+    # no policy at all there is nothing to simulate, so it falls back to the home
+    # country's own first blocked subdivision — or, failing that, the home
+    # country itself, which at least exercises the resolved-location path.
+    # "US-WA" -> "WA" at home, "CU-" -> "CU" abroad. The token is the storage
+    # form; a person reading a flash message wants the place.
+    def place_name(region)
+      Studio::Geo.parse_region(region, home_country: Studio.geo_home_country).compact.last || region
+    end
+
+    def simulated_region
+      configured = Studio.geo_simulated_region.presence
+      return Studio::Geo.normalize_region_token(configured, home_country: Studio.geo_home_country) if configured
+
+      subdivision = Studio::GeoSetting.effective_banned_subdivisions.first
+      return subdivision if subdivision
+
+      country = Studio::GeoSetting.effective_banned_countries.first
+      # "CU-" is a country with no subdivision — the shape Studio::Geo reads back
+      # as [country, nil], which is exactly what a country-wide block looks like
+      # to the policy.
+      country ? "#{country}-" : nil
+    end
+  end
+end

data/app/helpers/studio/geo_helper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Studio
+  # View-side geo: the flag art and the words. The decisions all live in
+  # Studio::Geo — this is the thin layer that turns a code into something a page
+  # can render, and it is where the asset lookup lives because only a view knows
+  # about the asset pipeline.
+  #
+  # Method names are `geo_`-prefixed on purpose. Rails includes every helper
+  # module into every view, so an unprefixed `country_flag_emoji` here would
+  # collide with a host app's own helper of that name during the window between
+  # this gem release and that app deleting its copy — and the collision resolves
+  # silently, by include order, to whichever was loaded last.
+  module GeoHelper
+    # Subdivision flags ship WITH the gem (app/assets/images/state-flags) so an
+    # app gets the complete badge from an empty repository. Only the US set is
+    # shipped today; every other country renders the emoji flag instead, which
+    # needs no bytes at all.
+    FLAG_ASSET_DIR = File.expand_path("../../assets/images/state-flags", __dir__)
+
+    def geo_country_flag_emoji(alpha2)
+      Studio::Geo.country_flag_emoji(alpha2)
+    end
+
+    def geo_foreign?(country)
+      Studio::Geo.foreign?(country, home_country: Studio.geo_home_country)
+    end
+
+    def geo_subdivision_name(code, country: Studio.geo_home_country)
+      Studio::Geo.subdivision_name(code, country: country)
+    end
+
+    # The asset path for a subdivision's flag, or nil when the gem ships no art
+    # for it. Nil is a normal answer, not an error: the badge renders the code
+    # text-only, which is exactly what a country outside the shipped set gets.
+    #
+    # Guarded on the COUNTRY as well as the code, and that guard is the important
+    # one: the lookup matches a bare two-letter code, so an Italian region
+    # normalising to "CA" would otherwise be handed the CALIFORNIA flag — a wrong
+    # answer that looks right.
+    #
+    # The guard is `== home`, NOT `unless foreign?`, and the difference is a case
+    # a mutation found in turf-monster's suite: an UNPARSEABLE country ("XX!")
+    # is not foreign by `foreign?` — deliberately, so the policy's fail-closed
+    # branch still treats it as home — and would therefore have been handed a
+    # home subdivision flag. Rendering art is the stricter question: show it only
+    # when the country is positively the home one.
+    # The small raster of the same flag, for a page that renders dozens at once.
+    # The SVG set is real vector art — several files run past a megabyte — so a
+    # 52-square grid of them is ~10 MB of downloads for something painted at 16px.
+    # These are 64x48 PNGs, ~4 KB each, rendered from the same source art.
+    def geo_subdivision_flag_thumb_path(code, country: Studio.geo_home_country)
+      geo_subdivision_flag_path(code, country: country, variant: "thumb/", extension: "png")
+    end
+
+    def geo_country_name(code)
+      Studio::Geo.country_name(code)
+    end
+
+    def geo_subdivision_flag_path(code, country: Studio.geo_home_country, variant: "", extension: "svg")
+      home = Studio::Geo.normalize_country(Studio.geo_home_country)
+      return nil unless Studio::Geo.normalize_country(country) == home
+
+      subdivision = Studio::Geo.normalize_subdivision(code)
+      return nil if subdivision.nil?
+
+      file = "#{variant}#{subdivision.downcase}.#{extension}"
+      return nil unless File.exist?(File.join(FLAG_ASSET_DIR, file))
+
+      image_path("state-flags/#{file}")
+    end
+  end
+end

data/app/models/studio/geo_setting.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Studio
+  # The operator's geo choices for THIS app: whether the gate is live, which
+  # countries it refuses outright, and which subdivisions of which country.
+  #
+  # One row per app (keyed by Studio.app_name), exactly like ThemeSetting — the
+  # engine's other "this deployment's settings" table. The gate reads this row and
+  # the published exclusion page renders THIS row, so the policy a visitor is told
+  # about can never drift from the policy that is enforced.
+  #
+  # STORAGE VOCABULARY: `banned_subdivisions` holds region tokens — "US-WA", not
+  # "WA" — because a bare code cannot say whether "CA" is California or Canada.
+  # Bare codes are still accepted on the way in (an app migrating years of them
+  # has a list of bare codes) and normalized against Studio.geo_home_country
+  # before they are written. See Studio::Geo for the full vocabulary.
+  #
+  # NIL-SAFE THROUGHOUT, because the table is installed by a migration the host
+  # runs. An app that has not run it yet must still boot, still serve, and still
+  # answer "is this visitor blocked?" — with "no", since an app with no geo row
+  # has declared no policy to enforce.
+  class GeoSetting < ApplicationRecord
+    include Sluggable
+
+    self.table_name = "studio_geo_settings"
+
+    validates :app_name, presence: true, uniqueness: true
+
+    before_validation :normalize_lists
+
+    class << self
+      # This app's row, or an unsaved instance carrying the configured defaults.
+      # Never nil, so a caller can always ask it a question.
+      def current
+        return new(default_attributes) unless table_ready?
+
+        find_by(app_name: Studio.app_name) || new(default_attributes)
+      end
+
+      # The PUBLISHED exclusion list, as region tokens. Falls back to the
+      # configured defaults when no row has been provisioned yet, so a fresh app
+      # publishes the same list it enforces from its first request.
+      def effective_banned_subdivisions
+        setting = current
+        list = setting.persisted? ? setting.banned_subdivisions : Studio.geo_default_banned_subdivisions
+        normalize_tokens(list)
+      end
+
+      def effective_banned_countries
+        setting = current
+        list = setting.persisted? ? setting.banned_countries : Studio.geo_default_banned_countries
+        Array(list).filter_map { |code| Studio::Geo.normalize_country(code) }.uniq.sort
+      end
+
+      # The gate is LIVE — a provisioned, enabled row. When false nothing is
+      # geo-restricted at all, including the fail-closed branch: that is the
+      # operator's kill switch, and it has to mean OFF rather than "off except
+      # for the visitors we cannot place".
+      def enforcing?
+        setting = current
+        setting.persisted? && setting.enabled?
+      end
+
+      # The verdict for one visitor. Pure policy lives in Studio::Geo; this
+      # method's only job is to hand it this app's stored choices.
+      def blocked?(country:, subdivision:)
+        setting = current
+        return false unless setting.persisted? && setting.enabled?
+
+        Studio::Geo.blocked?(
+          country: country,
+          subdivision: subdivision,
+          banned_countries: setting.banned_countries,
+          banned_subdivisions: setting.banned_subdivisions,
+          home_country: Studio.geo_home_country,
+          enforcing: true,
+          fail_closed: Studio.geo_fail_closed
+        )
+      end
+
+      # Bare subdivision codes for one country — what a checkbox grid renders and
+      # what a published list prints. "US-WA" -> "WA" for country "US".
+      def banned_subdivision_codes(country: Studio.geo_home_country)
+        prefix = "#{Studio::Geo.normalize_country(country)}-"
+        effective_banned_subdivisions.filter_map { |token| token.delete_prefix(prefix) if token.start_with?(prefix) }
+      end
+
+      def default_attributes
+        {
+          app_name: Studio.app_name,
+          enabled: false,
+          banned_countries: Array(Studio.geo_default_banned_countries),
+          banned_subdivisions: normalize_tokens(Studio.geo_default_banned_subdivisions)
+        }
+      end
+
+      def normalize_tokens(list)
+        Array(list)
+          .filter_map { |token| Studio::Geo.normalize_region_token(token, home_country: Studio.geo_home_country) }
+          .uniq
+          .sort
+      end
+
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError, NameError
+        false
+      end
+    end
+
+    # Bare codes for the grid — the instance half of .banned_subdivision_codes,
+    # reading THIS row rather than the effective list.
+    def subdivision_codes(country: Studio.geo_home_country)
+      prefix = "#{Studio::Geo.normalize_country(country)}-"
+      Array(banned_subdivisions).filter_map { |token| token.delete_prefix(prefix) if token.to_s.start_with?(prefix) }
+    end
+
+    def name_slug
+      "geo-#{app_name.to_s.parameterize}"
+    end
+
+    private
+
+    # One vocabulary in the column. Whatever the form posted — bare codes from a
+    # US grid, tokens from a country editor, blanks from unchecked boxes — is
+    # canonicalised here rather than at each read site, so a later reader never
+    # has to guess which form it is holding.
+    def normalize_lists
+      self.banned_subdivisions = self.class.normalize_tokens(banned_subdivisions)
+      self.banned_countries = Array(banned_countries)
+        .filter_map { |code| Studio::Geo.normalize_country(code) }
+        .uniq
+        .sort
+      self.app_name = Studio.app_name if app_name.blank?
+    end
+  end
+end

data/app/views/components/_geo_badge.html.erb

@@ -0,0 +1,63 @@
+<%# The visitor's detected location — PUBLIC, no sign-in required.
+
+    Detection is IP-based and runs for every request (Studio::GeoDetection), so
+    the badge can always say where the browser appears to be:
+
+      · a subdivision flag + code for a home-country visitor ("WA")
+      · a country flag emoji + region name for anyone else ("🇨🇦 Alberta")
+      · a red "??" when the location cannot be resolved at all — which is not a
+        cosmetic state: under the fail-closed rule an undetectable home-country
+        visitor is treated as BLOCKED, and the badge has to say so rather than
+        quietly render nothing
+
+    Red also means blocked-by-policy, or a simulated location an operator has
+    pinned from /admin/geo.
+
+    THE BLOCKED LOOK IS AN ATTRIBUTE, not a class list, so anything that knows
+    the policy changed can repaint the badge by flipping one attribute — which is
+    exactly what /admin/geo's live preview does while an operator ticks regions,
+    before anything is saved.
+
+    Locals are optional. With none, the badge reads the request's own detection;
+    passing them renders a specimen (the style guide, a view test) with no
+    session at all. %>
+<%
+  subdivision = local_assigns.key?(:subdivision) ? local_assigns[:subdivision] : geo_state
+  country     = local_assigns.key?(:country)     ? local_assigns[:country]     : geo_country
+  blocked     = local_assigns.key?(:blocked)     ? local_assigns[:blocked]     : geo_blocked?
+  simulated   = local_assigns.key?(:simulated)   ? local_assigns[:simulated]   : geo_override_active?
+
+  # A home-country subdivision flag is ONLY correct for a home-country visitor.
+  # The lookup matches a bare two-letter code, so a foreign region normalising to
+  # "CA" would be shown the CALIFORNIA flag — wrong, and wrong in the way that
+  # looks right. Outside the home country we render the country's emoji flag and
+  # never consult the subdivision art at all.
+  foreign       = geo_foreign?(country)
+  country_flag  = foreign ? geo_country_flag_emoji(country) : nil
+  flag_path     = foreign ? nil : geo_subdivision_flag_path(subdivision, country: country)
+  label         = subdivision.presence || (foreign ? country : nil) || "??"
+%>
+<% unless @_studio_geo_badge_css %>
+  <% @_studio_geo_badge_css = true %>
+  <style>
+    /* One rule owns the blocked look, so a repaint is one attribute. */
+    .geo-badge[data-blocked="true"] {
+      background-color: rgb(239 68 68 / 0.1);
+      border-color: rgb(239 68 68 / 0.3);
+      color: rgb(248 113 113);
+    }
+  </style>
+<% end %>
+<span class="geo-badge inline-flex items-center gap-1.5 text-xs font-mono px-2 py-0.5 rounded-lg whitespace-nowrap
+  <%= subdivision.present? ? 'bg-surface-alt text-secondary border border-subtle' : 'bg-surface-alt text-muted border border-subtle' %>"
+  data-geo-badge
+  data-country="<%= country %>"
+  data-subdivision="<%= subdivision %>"
+  data-blocked="<%= (simulated || blocked).to_s %>">
+  <% if country_flag %>
+    <span aria-label="<%= country %>" role="img" style="line-height: 1; flex-shrink: 0;"><%= country_flag %></span>
+  <% elsif flag_path %>
+    <img src="<%= flag_path %>" alt="<%= subdivision %>" class="rounded-sm" style="height: 12px; width: 16px; object-fit: cover; flex-shrink: 0;">
+  <% end %>
+  <%= label %>
+</span>