studio-engine 0.47.2 → 0.49.0

data/lib/studio/oauth_identity.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# The OAuth identity bound to an account — is Google linked, and is it safe to
+# unlink it?
+#
+# Pure Ruby and duck-typed, like Studio::ProfileImage: it takes anything that
+# answers `provider` / `uid` / `email`, so the rules are unit-testable without a
+# users table, and a host whose model has none of those columns is simply
+# reported as "not linked" rather than raising.
+#
+# THE ORPHAN GUARD IS THE REASON THIS FILE EXISTS. turf-monster's
+# AccountsController#unlink_google is one line — `update!(provider: nil, uid: nil)`
+# — with no check at all. For an account whose ONLY sign-in is Google (blank
+# email, so no magic link; no wallet; no password) that button silently locks
+# someone out of their own account, and the label just says "Unlink". It is safe
+# in turf today only because turf's users happen to carry an email; that is a
+# property of turf's data, not of the code, and the engine ships to apps whose
+# data it has never seen.
+#
+# So the engine asks first: after this unlink, is there still a way back in?
+module Studio
+  module OauthIdentity
+    # Both spellings appear across the ecosystem: `google_oauth2` is the OmniAuth
+    # strategy name that lands in users.provider, and `google` is what
+    # Studio.auth_methods calls the same thing. Matching both means a host that
+    # stored either is read correctly rather than reported as unlinked.
+    GOOGLE_PROVIDERS = %w[google google_oauth2].freeze
+
+    module_function
+
+    def google_linked?(user)
+      return false unless user.respond_to?(:provider) && user.respond_to?(:uid)
+
+      GOOGLE_PROVIDERS.include?(user.provider.to_s) && user.uid.present?
+    end
+
+    # Every way this account could sign in if Google were gone. Returns symbols
+    # so a caller can name what is left in a message rather than just refusing.
+    #
+    # Gated on Studio.auth_methods, not just on the column: an app that has an
+    # email column but does not offer magic-link sign-in cannot use it to get
+    # back in, and counting it would be exactly the wrong answer.
+    def remaining_sign_ins(user, auth_methods: Studio.auth_methods)
+      methods = Array(auth_methods).map(&:to_sym)
+      remaining = []
+
+      remaining << :magic_link if methods.include?(:magic_link) && present?(user, :email)
+      remaining << :wallet     if methods.include?(:wallet) && wallet_present?(user)
+      # `Studio.password_login_available?` — NOT a bare password_digest check.
+      # A digest can be a FOSSIL: turf-monster removed `has_secure_password` and
+      # kept the column, so rows still carry digests no code can authenticate
+      # against. Counting one as a way back in is a false positive in the
+      # dangerous direction — it would permit an unlink that orphans the account.
+      # The engine already ships the correct composite predicate
+      # (auth_method?(:password) && the User answering `authenticate`).
+      remaining << :password if methods.include?(:password) &&
+                                Studio.password_login_available? &&
+                                present?(user, :password_digest)
+
+      remaining
+    end
+
+    # The question the controller actually asks before unlinking.
+    def unlink_orphans_account?(user, auth_methods: Studio.auth_methods)
+      remaining_sign_ins(user, auth_methods: auth_methods).empty?
+    end
+
+    def present?(user, attribute)
+      user.respond_to?(attribute) && user.public_send(attribute).present?
+    end
+
+    # ONLY the explicitly configured wallet column — no fallback to a
+    # conventional name, deliberately.
+    #
+    # A convention-guessed reader is a false positive waiting to happen, and
+    # turf-monster is the live example: its `User#solana_address` returns
+    # `web3_solana_address || web2_solana_address`, and only the WEB3 address can
+    # actually sign in (SolanaSessionsController verifies a wallet signature; the
+    # web2 address is a custodial account with no signer). Guessing that reader
+    # would count a custodial address as a way back in and permit an unlink that
+    # orphans the account.
+    #
+    # So an app that has not named its signing-wallet column is treated as having
+    # no wallet sign-in. That errs toward REFUSING an unlink, which is the safe
+    # direction: the cost is an occasional refusal the operator can resolve by
+    # configuring `Studio.wallet_address_method`; the cost of the other direction
+    # is someone locked out of their account.
+    def wallet_present?(user)
+      configured = Studio.wallet_address_method
+      return false if configured.blank?
+
+      present?(user, configured)
+    end
+  end
+end

data/lib/studio/profile_image.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# The house rule for "is this upload an acceptable profile picture?" — one
+# allowlist, one size cap, in one place.
+#
+# Pure Ruby and duck-typed on purpose: it takes anything answering
+# `content_type` and `size`, which is what an ActionDispatch::Http::UploadedFile
+# answers, so the rule is unit-testable without Rails, a request, or a users
+# table.
+#
+# LIFTED FROM turf-monster, where this lived as ApplicationController#valid_image?
+# with an IMAGE_UPLOAD_TYPES constant beside it. Same allowlist, same 8 MB cap —
+# the values are turf's, deliberately, because they are the ones that have been
+# in front of real uploads. What changes is that the second and third app no
+# longer have to re-derive them.
+#
+# ON THE ALLOWLIST BEING AN ALLOWLIST: an avatar is attacker-supplied bytes that
+# the app then serves back to other people. Naming the three formats we accept is
+# what keeps an SVG — which is a script host, not a picture — from becoming a
+# profile photo. Do not widen this to a `start_with?("image/")` check.
+module Studio
+  module ProfileImage
+    ALLOWED_CONTENT_TYPES = %w[image/png image/jpeg image/webp].freeze
+
+    # 8 MB. Phone cameras clear this comfortably; it is a bound on abuse, not on
+    # the user's actual photo.
+    MAX_BYTES = 8 * 1024 * 1024
+
+    # A human sentence for the rejection path. Kept next to the rule so the two
+    # cannot drift — a message naming the wrong limit is worse than none.
+    MESSAGE = "Use a PNG, JPG, or WebP under 8 MB."
+
+    module_function
+
+    def acceptable?(file)
+      return false unless file.respond_to?(:content_type) && file.respond_to?(:size)
+      return false unless ALLOWED_CONTENT_TYPES.include?(file.content_type)
+
+      size = file.size
+      size.is_a?(Numeric) && size.positive? && size <= MAX_BYTES
+    end
+  end
+end

data/lib/studio/profile_sections.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+# Resolves Studio.profile_sections — the rows that make up the shared /profile
+# page — for a given view context. Pure Ruby (no Rails dependency) so the unit
+# suite exercises the resolution rules without booting the dummy app.
+#
+# THE SHAPE IS DELIBERATELY THE SIDEBAR'S. Studio.sidebar_sections already taught
+# this codebase one way to let a host declare page furniture: a static Array or a
+# callable that receives the view, symbolized on the way out, with sections the
+# viewer may not see dropped before render. Reusing that shape means a host that
+# has declared a sidebar already knows how to declare a profile.
+#
+# What a section looks like:
+#
+#   { key: :avatar, title: "Profile photo", partial: "studio/profiles/avatar_section",
+#     locals: { ... }, requires: :avatar, admin: false }
+#
+#   key      — stable identifier. A host removes or replaces a default by key,
+#              so reordering the defaults never breaks a host's override.
+#   title    — the row's heading.
+#   partial  — the partial to render. Host partials are ordinary app views.
+#   locals   — optional Hash passed to the partial.
+#   requires — optional attribute (or Array of them) the CURRENT USER must
+#              respond to for the row to render. See below.
+#   admin    — admin-only row, same rule as the sidebar's.
+#   if       — optional callable. The row renders only when it returns truthy.
+#              Called with the view when it takes an argument, without when it
+#              does not. This is the APP-CAPABILITY gate, distinct from
+#              `requires:` which is the MODEL gate — and the two really are
+#              different questions. Every consumer's users table carries
+#              `provider` and `uid`, so `requires:` alone selected the whole
+#              fleet for the Google row; mcritchie-industries has those columns
+#              AND `auth_methods = %i[magic_link]` with no omniauth gem at all,
+#              so it would have rendered a "Link Google Account" button leading
+#              nowhere. Having a column is not the same as offering the feature.
+#   modals   — the row opens the shared crop/saving modals. The PAGE mounts them
+#              once (studio/modals/_scoped_host on a "profileModals" store) when
+#              any resolved row asks for them, so a row never has to know whether
+#              the host app renders a modal host of its own. Two of the five
+#              consumers render none at all, and the two that do ship a FORK of
+#              the engine's shared host that would shadow it.
+#
+# ON `requires` — this is the whole reason the registry exists rather than a
+# hardcoded page. The consuming apps do NOT agree on their users table:
+# mcritchie-industries has eight columns and no `first_name`; turf-monster has
+# forty. A shared page that assumed a column would raise NoMethodError on every
+# signed-in request in the app that lacked it — the same failure mode
+# Studio.first_name_outstanding? already guards against with respond_to?.
+#
+# So a row DECLARES what it needs and is dropped when the host cannot serve it.
+# mcritchie-industries gets a working profile page with an avatar row and no name
+# row until it installs the standard-profile-columns migration, at which point
+# the row appears with no code change. Silence, not a 500.
+module Studio
+  module ProfileSections
+    # The page every consumer gets for free. Iteration one is deliberately two
+    # rows: the picture and the name. Everything else the account-standardization
+    # program lifts (email change, identities, preferences) arrives as further
+    # defaults, and a host that has declared its own list keeps working because
+    # it composes against `Studio.default_profile_sections` rather than a literal.
+    DEFAULTS = [
+      { key: :avatar, title: "Profile photo",
+        partial: "studio/profiles/avatar_section", requires: :avatar, modals: true },
+      { key: :first_name, title: "Your name",
+        partial: "studio/profiles/first_name_section", requires: :first_name },
+      { key: :email, title: "Email",
+        partial: "studio/profiles/email_section", requires: :email },
+      # Gated on the app OFFERING Google, not merely on having the columns —
+      # the same question app/views/sessions/new.html.erb already asks before
+      # drawing this identical button on the login page.
+      { key: :google, title: "Google account",
+        partial: "studio/profiles/google_section", requires: %i[provider uid],
+        if: -> { Studio.auth_method?(:google) } }
+    ].freeze
+
+    module_function
+
+    # A fresh, mutable copy every call. Hosts compose with `+` and sometimes
+    # `reject`, and handing out the frozen literal would let one host's edit
+    # leak into the next request's page.
+    def defaults
+      DEFAULTS.map { |section| section.dup }
+    end
+
+    # Declared may be nil (the host has said nothing — it gets the defaults), an
+    # Array, or a callable receiving the view context.
+    #
+    # `nil` meaning "the defaults" rather than "no sections" is the load-bearing
+    # choice here: it is what makes a brand-new app's profile page work with an
+    # empty initializer, which is the entire point of standardizing this.
+    def resolve(declared, view)
+      sections = declared.respond_to?(:call) ? declared.call(view) : declared
+      sections = defaults if sections.nil?
+
+      admin = view.respond_to?(:admin?) && view.admin?
+      user  = view.respond_to?(:current_user) ? view.current_user : nil
+
+      Array(sections)
+        .map { |section| symbolize(section) }
+        .reject { |section| section[:admin] && !admin }
+        .select { |section| enabled?(section[:if], view) }
+        .select { |section| served_by?(user, section[:requires]) }
+    end
+
+    # The app-capability gate. No `if:` means always enabled. The callable takes
+    # the view when it wants one and nothing when it does not, so a host can
+    # write either `-> { Studio.feature?(:x) }` or `->(view) { view.admin? }`.
+    def enabled?(condition, view)
+      return true if condition.nil?
+
+      # A Symbol/String names a method on the VIEW — Rails' own
+      # `before_action ..., if: :method_name` convention, and therefore the most
+      # natural thing a host will write here.
+      #
+      # It is handled explicitly because the alternative FAILS OPEN: a Symbol
+      # does not answer `call`, so the earlier `return !!condition` coerced
+      # `:some_predicate` to true and rendered the row unconditionally — a gate
+      # that silently does nothing, in the same permissive direction as the bug
+      # this whole `if:` key was added to fix. A host would have had no signal.
+      if condition.is_a?(Symbol) || condition.is_a?(String)
+        unless view.respond_to?(condition)
+          # SILENT would repeat the bug this key was added to fix. The old
+          # coercion gave the host no signal; dropping the row without one only
+          # moves the silence somewhere safer. A typo'd gate now says so.
+          warn_gate("profile_sections: `if: #{condition.inspect}` names a method the view " \
+                    "does not answer — the row was dropped. Check the spelling.")
+          return false
+        end
+
+        # Arity-aware, matching the lambda branch below: a predicate written as
+        # `def visible?(view)` is as natural as one written without an argument,
+        # and calling it wrong raises ArgumentError — which surfaces as a 500 on
+        # /profile rather than as a dropped row.
+        method = view.method(condition)
+        return !!(method.arity.zero? ? view.public_send(condition) : view.public_send(condition, view))
+      end
+
+      return !!condition unless condition.respond_to?(:call)
+
+      !!(condition.arity.zero? ? condition.call : condition.call(view))
+    end
+
+    # Can this host's user model serve the row? No requirement means yes — a row
+    # that reads nothing off the user (a static explainer, a link out) is always
+    # served. A nil user means we are rendering for nobody, and nothing is served.
+    def served_by?(user, requires)
+      needed = Array(requires).compact
+      return true if needed.empty?
+      return false if user.nil?
+
+      needed.all? { |attribute| user.respond_to?(attribute) }
+    end
+
+    # Pure Ruby: this file loads without Rails, so it cannot assume a logger.
+    def warn_gate(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        Kernel.warn(message)
+      end
+    end
+
+    def symbolize(hash)
+      out = hash.to_h.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+
+      # `key` is an IDENTIFIER, so its VALUE symbolizes too — unlike every other
+      # field, whose value is data. A host composing by key writes
+      # `reject { |s| s[:key] == :avatar }`, and that silently matches nothing if
+      # a section declared with string keys kept `"avatar"` as a String. Removing
+      # a standard row is the documented seam; it must not depend on which
+      # spelling the host happened to use.
+      out[:key] = out[:key].to_sym if out[:key].respond_to?(:to_sym)
+      out
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.47.2"
+  VERSION = "0.49.0"
 end

data/lib/studio.rb

@@ -7,6 +7,9 @@ require "studio/environment_banner"
 require "studio/theme_resolver"
 require "studio/ui_primitives"
 require "studio/sidebar_sections"
+require "studio/profile_sections"
+require "studio/profile_image"
+require "studio/oauth_identity"
 require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
@@ -83,6 +86,49 @@ module Studio
   #   end
   mattr_accessor :sidebar_sections, default: []
 
+  # ---- The shared profile page (/profile) ----
+  # The rows that make up /profile. `nil` — the default — means "the engine's
+  # standard page", NOT "no rows": a brand-new app with an empty initializer gets
+  # a working profile page, which is the entire point of standardizing it.
+  #
+  # Declare an Array (or a callable receiving the view) to customize. Compose
+  # against Studio.default_profile_sections rather than a literal, so a later
+  # engine release that adds a standard row delivers it to you:
+  #
+  #   Studio.configure do |config|
+  #     config.profile_sections = ->(view) {
+  #       Studio.default_profile_sections +
+  #         [ { key: :wallet, title: "Identities", partial: "profiles/wallet" } ]
+  #     }
+  #   end
+  #
+  # Drop a standard row by key instead of restating the list:
+  #
+  #   config.profile_sections = Studio.default_profile_sections.reject { |s| s[:key] == :avatar }
+  #
+  # Shape and resolution rules: lib/studio/profile_sections.rb. A row may declare
+  # `requires:` — an attribute the current user must respond to — and is dropped
+  # when this host's model does not have it, so the page tolerates the fact that
+  # the consuming apps' users tables genuinely disagree.
+  mattr_accessor :profile_sections, default: nil
+
+  # Whether Studio.routes draws /profile (Studio::ProfilesController).
+  #
+  # ON BY DEFAULT, and it is worth saying why this one can be when
+  # draw_admin_emails_routes and draw_onboarding_routes could not: those two
+  # claimed helper names a consumer ALREADY OWNED, so drawing them raised
+  # `Invalid route name, already in use` while that app's routes.rb loaded and
+  # took down its entire route set. `profile` is claimed by none of the five
+  # consumers — mcritchie-studio, mcritchie-industries, turf-monster, moms-app
+  # and acquisition-studio were each checked (2026-08-14) — and turf-monster's
+  # nearest names are complete_profile_account_path / save_profile_account_path,
+  # which do not collide.
+  #
+  # That is exactly why the shared page is /profile and not /account: turf owns
+  # account_path, and a shared /account could never be default-on. An app that
+  # wants the page gone still sets this false.
+  mattr_accessor :draw_profile_routes, default: true
+
   # How long a freshly minted magic link stays live.
   mattr_accessor :magic_link_ttl, default: 15.minutes
 
@@ -179,6 +225,17 @@ module Studio
   # later session may ask again. That is the whole reason this is not a column.
   FIRST_NAME_SKIP_SESSION_KEY = :onboarding_skipped_first_name
 
+  # How long a first name may be. ONE constant because users.first_name is
+  # written from TWO surfaces — the onboarding step (seconds after signup) and
+  # /profile (any time after) — and rendered by a third, the profile form's
+  # maxlength. Two independently-correct caps that disagreed would let onboarding
+  # accept a name /profile then refused to save, a bug with no obvious owner.
+  #
+  # Keeping it here rather than on either controller also keeps the VIEW off a
+  # controller constant: the form needs the number, and a view reaching into
+  # Studio::ProfilesController to get it would couple the two for no reason.
+  FIRST_NAME_MAX_LENGTH = 40
+
   # The shared rule for "does this account still owe us a first name?" — the one
   # piece of onboarding logic every app agrees on. Hosts compose it into their own
   # flow rather than re-deriving it (turf's OnboardingFlow calls straight through).
@@ -545,6 +602,21 @@ module Studio
     SidebarSections.resolve(sidebar_sections, view)
   end
 
+  # The engine's standard /profile rows. Hosts compose against this rather than
+  # restating a literal list, so a later release that adds a standard row
+  # delivers it to every app that used the seam as intended.
+  def self.default_profile_sections
+    ProfileSections.defaults
+  end
+
+  # Profile rows resolved for a view context: a callable config is called with
+  # the view, keys symbolize, admin-only rows drop for non-admin viewers, and
+  # rows this host's user model cannot serve drop entirely. `nil` config resolves
+  # to the standard page.
+  def self.profile_sections_for(view)
+    ProfileSections.resolve(profile_sections, view)
+  end
+
   def self.env_truthy?(value)
     %w[1 true yes on].include?(value.to_s.strip.downcase)
   end
@@ -602,6 +674,25 @@ module Studio
         post "auth/solana/verify", to: "solana_sessions#verify", as: :solana_verify
       end
 
+      # The shared profile page. ON by default — unlike /admin/emails and the
+      # onboarding pair, `profile` is claimed by no consumer, so drawing it
+      # cannot take an app's route set down. See Studio.draw_profile_routes.
+      #
+      # Avatar is its own PATCH rather than a field on #update: an attachment
+      # param submitted empty PURGES the attachment, so a single form carrying
+      # both would delete someone's photo every time they edited their name.
+      if Studio.draw_profile_routes
+        get    "profile",        to: "studio/profiles#show",   as: :profile
+        patch  "profile",        to: "studio/profiles#update"
+        patch  "profile/avatar", to: "studio/profiles#avatar", as: :profile_avatar
+        # DELETE, because unlinking removes an identity. Linking is not drawn
+        # here: it is OmniAuth's own /auth/:provider, which the middleware owns.
+        patch  "profile/email",  to: "studio/profiles#email", as: :profile_email
+        delete "profile/google", to: "studio/profiles#unlink_google",
+               as: :profile_unlink_google
+
+      end
+
       resources :error_logs, only: [:index, :show]
 
       # Admin

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.47.2
+  version: 0.49.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -204,6 +204,7 @@ files:
 - app/controllers/studio/local_reviews_controller.rb
 - app/controllers/studio/models_controller.rb
 - app/controllers/studio/onboarding_controller.rb
+- app/controllers/studio/profiles_controller.rb
 - app/controllers/style_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
@@ -215,10 +216,12 @@ files:
 - app/jobs/studio/email_delivery_job.rb
 - app/mailers/application_mailer.rb
 - app/mailers/studio/newsletter_mailer.rb
+- app/mailers/studio/profile_mailer.rb
 - app/mailers/user_mailer.rb
 - app/models/concerns/sluggable.rb
 - app/models/concerns/studio/board/rankable.rb
 - app/models/concerns/studio/broadcastable.rb
+- app/models/concerns/studio/user_profile.rb
 - app/models/current.rb
 - app/models/error_log.rb
 - app/models/image_cache.rb
@@ -333,6 +336,13 @@ files:
 - app/views/studio/models/show.html.erb
 - app/views/studio/newsletter_mailer/subscribed.html.erb
 - app/views/studio/newsletter_mailer/subscribed.text.erb
+- app/views/studio/profile_mailer/email_change_notification.html.erb
+- app/views/studio/profile_mailer/email_change_notification.text.erb
+- app/views/studio/profiles/_avatar_section.html.erb
+- app/views/studio/profiles/_email_section.html.erb
+- app/views/studio/profiles/_first_name_section.html.erb
+- app/views/studio/profiles/_google_section.html.erb
+- app/views/studio/profiles/show.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_specimen.html.erb
@@ -373,6 +383,9 @@ files:
 - lib/studio/link_token.rb
 - lib/studio/log_rotation.rb
 - lib/studio/mail_transport.rb
+- lib/studio/oauth_identity.rb
+- lib/studio/profile_image.rb
+- lib/studio/profile_sections.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb
 - lib/studio/sidebar_sections.rb