studio-engine 0.56.4 → 0.57.1

data/lib/studio.rb

@@ -1,6 +1,8 @@
 require "studio/version"
 require "studio/log_rotation"
 require "studio/ip_locations"
+require "studio/geo"
+require "studio/geo/lookup"
 require "studio/engine"
 require "studio/color_scale"
 require "studio/environment_banner"
@@ -244,6 +246,74 @@ module Studio
   #   }
   mattr_accessor :onboarding_steps_resolver, default: ->(_user, _session) { [] }
 
+  # ---- Geo (Studio::Geo, Studio::GeoSetting, Studio::GeoDetection) ---------
+  #
+  # An app gets geo VALIDATION — where is this visitor, render their flag, is
+  # this location allowed — by including Studio::GeoDetection. It gets geo
+  # LOCKING by hanging `require_geo_allowed` on the surfaces it must not serve
+  # there. The engine deliberately does not decide which surfaces those are; see
+  # docs/GEO.md.
+
+  # This app's own country, ISO alpha-2. Two things read it: a bare subdivision
+  # code ("WA") is resolved as a subdivision OF this country, and the fail-closed
+  # rule fires only for visitors placed HERE with no detectable subdivision.
+  mattr_accessor :geo_home_country, default: "US"
+
+  # The policy a fresh app enforces before an operator has saved anything at
+  # /admin/geo. Countries are alpha-2 codes; subdivisions are region tokens
+  # ("US-WA"), though bare codes are accepted and normalized.
+  mattr_accessor :geo_default_banned_countries, default: []
+  mattr_accessor :geo_default_banned_subdivisions, default: []
+
+  # How to treat a HOME-COUNTRY visitor whose subdivision cannot be resolved (a
+  # VPN, a datacenter IP, a provider outage). true = blocked, because a blank
+  # could be any of the blocked regions masked by a failed lookup. An app whose
+  # geo rules are advisory rather than legal sets this false.
+  mattr_accessor :geo_fail_closed, default: true
+
+  # Freshness windows for the session-cached lookup. A RESOLVED region is trusted
+  # for a day; a BLANK one is retried within minutes, so a provider blip does not
+  # cache "nowhere" — and fail every gate closed — for 24 hours.
+  mattr_accessor :geo_ttl, default: 24.hours
+  mattr_accessor :geo_retry_ttl, default: 5.minutes
+
+  # Where a DEVELOPMENT session stands. Loopback never geocodes, so without this
+  # every geo-gated feature fails closed on a developer's own machine. Development
+  # only — test and production must report an unplaceable visitor honestly.
+  #
+  #   config.geo_development_region = ENV.fetch("DEV_GEO_STATE", "US-CO")
+  mattr_accessor :geo_development_region, default: nil
+
+  # The region /admin/geo's "simulate" button puts the operator in, so a blocked
+  # experience can be walked without a VPN. Defaults to the first blocked
+  # subdivision the app actually has, which is the one worth testing.
+  mattr_accessor :geo_simulated_region, default: nil
+
+  # What a blocked visitor is told, and where an HTML request lands. The message
+  # takes (subdivision, country) — both may be nil on the fail-closed path, which
+  # is why the default omits an empty "( )" rather than printing one.
+  mattr_accessor :geo_blocked_message, default: lambda { |subdivision, _country|
+    place = subdivision.present? ? " (#{subdivision})" : ""
+    "This feature is not available in your area#{place}."
+  }
+  mattr_accessor :geo_blocked_redirect, default: nil
+
+  # Draw /admin/geo + /geo/check from Studio.routes. OFF by default, for the same
+  # hard reason as draw_admin_emails_routes: turf-monster already owns
+  # admin_geo_path, admin_geo_update_path, admin_geo_toggle_path and
+  # geo_check_path, and a duplicate route NAME raises while that app's routes.rb
+  # is loading — taking its entire route set down, not just this page.
+  mattr_accessor :draw_geo_routes, default: false
+
+  # Whether the engine configures Geocoder on boot (provider, HTTPS, timeout, and
+  # a Rails.cache-backed IP cache). An app that configures Geocoder itself sets
+  # this false; an app with no geocoder gem is unaffected either way.
+  mattr_accessor :configure_geocoder, default: true
+  mattr_accessor :geo_ip_provider, default: :ipinfo_io
+  mattr_accessor :geo_ip_api_key, default: nil
+  mattr_accessor :geo_lookup_timeout, default: 3
+  mattr_accessor :geo_cache_ttl, default: 24.hours
+
   # Session key recording "asked, and they said not now". Session-scoped
   # DELIBERATELY: skipping means not now, not never — the field stays blank, so a
   # later session may ask again. That is the whole reason this is not a column.
@@ -731,6 +801,25 @@ module Studio
       patch "admin/theme",            to: "theme_settings#update",     as: :admin_theme_update
       post  "admin/theme/regenerate", to: "theme_settings#regenerate", as: :admin_theme_regenerate
       get   "admin/schema",           to: "schema#index",              as: :admin_schema
+
+      # The shared geo manager (/admin/geo) + the public detection probe
+      # (/geo/check). OPT-IN — see Studio.draw_geo_routes: turf-monster owns all
+      # four of these helper names today, and drawing a name an app already has
+      # raises `Invalid route name, already in use` while that app's routes.rb
+      # loads, which kills every route in it. An app opts in from its initializer
+      # once its local copies are deleted:
+      #
+      #   config.draw_geo_routes = true
+      #
+      # This gates only the PAGE and the probe. Detection, the badge, the policy
+      # and the gate are always available to an app that includes
+      # Studio::GeoDetection — an app is geo-aware whether or not it draws these.
+      if Studio.draw_geo_routes
+        get   "geo/check",        to: "studio/geo_settings#check",           as: :geo_check
+        get   "admin/geo",        to: "studio/geo_settings#edit",            as: :admin_geo
+        patch "admin/geo",        to: "studio/geo_settings#update",          as: :admin_geo_update
+        post  "admin/geo/toggle", to: "studio/geo_settings#toggle_override", as: :admin_geo_toggle
+      end
       # The living style guide. Canonical at /admin/style (StyleController#index);
       # /admin/design_system redirects here but KEEPS its admin_design_system_path
       # helper so a shipped host sidebar link on the old helper still resolves.

data/studio-engine.gemspec

@@ -37,4 +37,8 @@ Gem::Specification.new do |spec|
   # 500'd a host app's task board — declaring it here makes that impossible to repeat.
   spec.add_dependency "redis", ">= 4.0.1"
   spec.add_dependency "turbo-rails", ">= 1.0"
+  # IP -> location for Studio::Geo. A dependency rather than a host concern
+  # because the point of the geo primitive is that EVERY app has the capacity:
+  # an app that has to add a gem before it can place a visitor does not.
+  spec.add_dependency "geocoder", ">= 1.8", "< 2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.56.4
+  version: 0.57.1
 platform: ruby
 authors:
 - Alex McRitchie
@@ -154,6 +154,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: geocoder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Studio Engine is a non-isolated Rails engine that ships an opinionated
   authentication + SSO contract, a polymorphic ErrorLog model, a Sluggable concern,
   a 7-role dynamic theme system with CSS-custom-property generation, and an S3-backed
@@ -177,6 +197,110 @@ files:
 - app/assets/images/emails/newsletter-subscribed-background.gif
 - app/assets/images/resend-favicon.png
 - app/assets/images/ses-favicon.png
+- app/assets/images/state-flags/ak.svg
+- app/assets/images/state-flags/al.svg
+- app/assets/images/state-flags/ar.svg
+- app/assets/images/state-flags/az.svg
+- app/assets/images/state-flags/ca.svg
+- app/assets/images/state-flags/co.svg
+- app/assets/images/state-flags/ct.svg
+- app/assets/images/state-flags/dc.svg
+- app/assets/images/state-flags/de.svg
+- app/assets/images/state-flags/fl.svg
+- app/assets/images/state-flags/ga.svg
+- app/assets/images/state-flags/hi.svg
+- app/assets/images/state-flags/ia.svg
+- app/assets/images/state-flags/id.svg
+- app/assets/images/state-flags/il.svg
+- app/assets/images/state-flags/in.svg
+- app/assets/images/state-flags/ks.svg
+- app/assets/images/state-flags/ky.svg
+- app/assets/images/state-flags/la.svg
+- app/assets/images/state-flags/ma.svg
+- app/assets/images/state-flags/md.svg
+- app/assets/images/state-flags/me.svg
+- app/assets/images/state-flags/mi.svg
+- app/assets/images/state-flags/mn.svg
+- app/assets/images/state-flags/mo.svg
+- app/assets/images/state-flags/ms.svg
+- app/assets/images/state-flags/mt.svg
+- app/assets/images/state-flags/nc.svg
+- app/assets/images/state-flags/nd.svg
+- app/assets/images/state-flags/ne.svg
+- app/assets/images/state-flags/nh.svg
+- app/assets/images/state-flags/nj.svg
+- app/assets/images/state-flags/nm.svg
+- app/assets/images/state-flags/nv.svg
+- app/assets/images/state-flags/ny.svg
+- app/assets/images/state-flags/oh.svg
+- app/assets/images/state-flags/ok.svg
+- app/assets/images/state-flags/or.svg
+- app/assets/images/state-flags/pa.svg
+- app/assets/images/state-flags/pr.svg
+- app/assets/images/state-flags/ri.svg
+- app/assets/images/state-flags/sc.svg
+- app/assets/images/state-flags/sd.svg
+- app/assets/images/state-flags/thumb/ak.png
+- app/assets/images/state-flags/thumb/al.png
+- app/assets/images/state-flags/thumb/ar.png
+- app/assets/images/state-flags/thumb/az.png
+- app/assets/images/state-flags/thumb/ca.png
+- app/assets/images/state-flags/thumb/co.png
+- app/assets/images/state-flags/thumb/ct.png
+- app/assets/images/state-flags/thumb/dc.png
+- app/assets/images/state-flags/thumb/de.png
+- app/assets/images/state-flags/thumb/fl.png
+- app/assets/images/state-flags/thumb/ga.png
+- app/assets/images/state-flags/thumb/hi.png
+- app/assets/images/state-flags/thumb/ia.png
+- app/assets/images/state-flags/thumb/id.png
+- app/assets/images/state-flags/thumb/il.png
+- app/assets/images/state-flags/thumb/in.png
+- app/assets/images/state-flags/thumb/ks.png
+- app/assets/images/state-flags/thumb/ky.png
+- app/assets/images/state-flags/thumb/la.png
+- app/assets/images/state-flags/thumb/ma.png
+- app/assets/images/state-flags/thumb/md.png
+- app/assets/images/state-flags/thumb/me.png
+- app/assets/images/state-flags/thumb/mi.png
+- app/assets/images/state-flags/thumb/mn.png
+- app/assets/images/state-flags/thumb/mo.png
+- app/assets/images/state-flags/thumb/ms.png
+- app/assets/images/state-flags/thumb/mt.png
+- app/assets/images/state-flags/thumb/nc.png
+- app/assets/images/state-flags/thumb/nd.png
+- app/assets/images/state-flags/thumb/ne.png
+- app/assets/images/state-flags/thumb/nh.png
+- app/assets/images/state-flags/thumb/nj.png
+- app/assets/images/state-flags/thumb/nm.png
+- app/assets/images/state-flags/thumb/nv.png
+- app/assets/images/state-flags/thumb/ny.png
+- app/assets/images/state-flags/thumb/oh.png
+- app/assets/images/state-flags/thumb/ok.png
+- app/assets/images/state-flags/thumb/or.png
+- app/assets/images/state-flags/thumb/pa.png
+- app/assets/images/state-flags/thumb/pr.png
+- app/assets/images/state-flags/thumb/ri.png
+- app/assets/images/state-flags/thumb/sc.png
+- app/assets/images/state-flags/thumb/sd.png
+- app/assets/images/state-flags/thumb/tn.png
+- app/assets/images/state-flags/thumb/tx.png
+- app/assets/images/state-flags/thumb/ut.png
+- app/assets/images/state-flags/thumb/va.png
+- app/assets/images/state-flags/thumb/vt.png
+- app/assets/images/state-flags/thumb/wa.png
+- app/assets/images/state-flags/thumb/wi.png
+- app/assets/images/state-flags/thumb/wv.png
+- app/assets/images/state-flags/thumb/wy.png
+- app/assets/images/state-flags/tn.svg
+- app/assets/images/state-flags/tx.svg
+- app/assets/images/state-flags/ut.svg
+- app/assets/images/state-flags/va.svg
+- app/assets/images/state-flags/vt.svg
+- app/assets/images/state-flags/wa.svg
+- app/assets/images/state-flags/wi.svg
+- app/assets/images/state-flags/wv.svg
+- app/assets/images/state-flags/wy.svg
 - app/assets/javascripts/studio/alpine.js
 - app/assets/javascripts/studio/canvas_confetti.js
 - app/assets/javascripts/studio/sortable.js
@@ -189,6 +313,7 @@ files:
 - app/controllers/concerns/studio/admin_models.rb
 - app/controllers/concerns/studio/board/reorderable.rb
 - app/controllers/concerns/studio/error_handling.rb
+- app/controllers/concerns/studio/geo_detection.rb
 - app/controllers/concerns/studio/impersonation.rb
 - app/controllers/concerns/studio/link_consumption.rb
 - app/controllers/concerns/studio/magic_link_issuing.rb
@@ -202,6 +327,7 @@ files:
 - app/controllers/solana_sessions_controller.rb
 - app/controllers/studio/email_images_controller.rb
 - app/controllers/studio/emails_controller.rb
+- app/controllers/studio/geo_settings_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/studio/local_reviews_controller.rb
@@ -213,6 +339,7 @@ files:
 - app/helpers/studio/admin_models_table_helper.rb
 - app/helpers/studio/at_time_helper.rb
 - app/helpers/studio/fizz_helper.rb
+- app/helpers/studio/geo_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
@@ -233,6 +360,7 @@ files:
 - app/models/studio/email_delivery.rb
 - app/models/studio/email_setting.rb
 - app/models/studio/enumeral.rb
+- app/models/studio/geo_setting.rb
 - app/models/studio/link.rb
 - app/models/studio/model_page.rb
 - app/models/theme_setting.rb
@@ -249,6 +377,7 @@ files:
 - app/views/components/_copy_button.html.erb
 - app/views/components/_emoji_swap.html.erb
 - app/views/components/_empty_state.html.erb
+- app/views/components/_geo_badge.html.erb
 - app/views/components/_google_logo.html.erb
 - app/views/components/_input.html.erb
 - app/views/components/_json_debug.html.erb
@@ -304,6 +433,7 @@ files:
 - app/views/studio/emails/orphan.html.erb
 - app/views/studio/emails/show.html.erb
 - app/views/studio/fields/_date_of_birth.html.erb
+- app/views/studio/geo_settings/edit.html.erb
 - app/views/studio/links/confirm.html.erb
 - app/views/studio/local_emails/index.html.erb
 - app/views/studio/mailers/_layered_banner.html.erb
@@ -388,6 +518,7 @@ files:
 - db/migrate/20260812220000_add_subject_to_studio_email_settings.rb
 - db/migrate/20260813010000_add_body_cta_footer_to_studio_email_settings.rb
 - db/migrate/20260813220000_add_standard_user_profile_columns.rb
+- db/migrate/20260818120000_create_studio_geo_settings.rb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/cable.rb
@@ -396,6 +527,9 @@ files:
 - lib/studio/email_smoke.rb
 - lib/studio/engine.rb
 - lib/studio/environment_banner.rb
+- lib/studio/geo.rb
+- lib/studio/geo/countries.rb
+- lib/studio/geo/lookup.rb
 - lib/studio/image_cache.rb
 - lib/studio/ip_locations.rb
 - lib/studio/link_resolution.rb