studio-engine 0.4.13 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b6894996dc059e056097232586c6cc442344d2185c2cd435add21e5f78f57f4
-  data.tar.gz: c2a7a5346ac290461292100403af6fda95ee301d346c8b8de23bf05c91fc6ee5
+  metadata.gz: '01761814c3988b2d5748c44b65122bb83678455e1ae1ee7f5daa1b949c1c0d65'
+  data.tar.gz: 42a25a49ff120d404827d22298440f1c0cb0b981c8a7c549aaf15e218fa666a8
 SHA512:
-  metadata.gz: 7280d2c5f81ce34a3a979bd7bad01b767646075949bebf93ebd3c6277758f96f54f0132a59e119abfdd3a8c4ecd01b08f08f4bcd386b8747ed3b3d8348e2dcba
-  data.tar.gz: 8f8e965dcb50315ec81c90f225fa916581bd02f00aba0d5fab9ddebb9d29528239dbff0e876c72854724f74820e6a1dbe1cc262d4bdfd3ab6957f3c2d6d60296
+  metadata.gz: 44831601ac48a7dfcfb68dcf0173e7c10aa5be021935fed8c609a44aca3736393b4e556dbcf45ae9a1c4bb4691682caaedb21c7e5316859c720e164189a886da
+  data.tar.gz: 3bbc9bcf51bc62253d7e034f64f6e26e80222e8ae5cdaeef148efcd0e99967ddabcaaf002a80a29ac941f9e04185621c74a1969a3822071db68f70e0a1970cb2

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Both consumer Rails apps pin to a tag in their `Gemfile`; bumping the tag is a release.
 
+## v0.5.0 (2026-06-02)
+
+Promotes the **shared authentication core** out of Turf Monster into the engine so every Studio app runs one passwordless-first auth flow. This release is the **backend** half (services, POROs, concern helpers, base controllers, mailer); the shared wallet JS + Connect-Wallet modal land with the first consumer wiring. Turf Monster is **not** on this version yet — it stays on 0.4.x until its incremental migration.
+
+### Added
+- **`Studio.auth_methods`** config (default `%i[magic_link google wallet]`; `:password` opt-in) + `Studio.auth_method?(m)`. Login/signup surfaces render a field/button per enabled method. `:password` also re-arms the `User#authenticate` contract check.
+- **`Studio.magic_link_ttl`** (15 min), **`Studio.magic_link_token_name`** (`"magic_link_v1"`), **`Studio.mailer_from`** config.
+- **`SessionContext`** PORO — canonical guest/web2/web3 viewer state (`mode`, `to_h` camelCase for `Alpine.store('session')`). Wallet predicates are `respond_to?`-guarded so a wallet-less app is safe.
+- **`Current`** baseline (`attribute :user`) — apps needing more request-scoped state override the file.
+- **`MagicLink`** service — signed, single-use (jti in `Rails.cache`), URL-safe token; token name/TTL from config.
+- **`GoogleOauthValidator`** — server-side `tokeninfo` re-check (audience / email_verified / expiry).
+- **`Solana::SessionAuth`** concern — Rails-session adapter over `solana-studio`'s `Solana::AuthVerifier` (nonce delete-before-verify + host binding). solana-studio is host-provided; only loaded when wallet sign-in is on.
+- **Base controllers** (generic; apps override for richer flows): `MagicLinksController` (create-or-login), `SolanaSessionsController` (nonce/verify), and an upgraded `OmniauthCallbacksController` (now runs `GoogleOauthValidator`).
+- **`UserMailer#magic_link`** + `ApplicationMailer` (proc `from:` ← `Studio.mailer_from`) + app-name-aware templates.
+- **Routes**: `Studio.routes` now draws `magic_link_request`/`magic_link` (when `:magic_link`) and `solana_nonce`/`solana_verify` (when `:wallet`), gated by `auth_method?`.
+
+### Concern (`Studio::ErrorHandling`)
+- `set_app_session` now binds a rotating `session[:session_token]` (OPSEC-045, guarded) and resets the `:onchain` flag; `clear_app_session` wipes both.
+- `require_authentication` is now **format-aware** (HTML→redirect, JSON/Turbo→401, was a blind redirect that 406'd AJAX — OPSEC-046).
+- New helpers: `set_current_context`, `verify_session_token` (guarded), `onchain_session?`, `wallet_context`, `client_session_payload` (identity-only baseline; apps override to merge balances).
+
+### Breaking / Migration
+- **`User.from_omniauth` contract is now `(auth, email_verified:)`** — the engine `OmniauthCallbacksController` passes the `GoogleOauthValidator` result. Consumers using the engine callback must update their `from_omniauth` to accept the kwarg.
+- Consumers enabling `:magic_link` / `:wallet` must provide the User class methods the base controllers call (`User.find_by(email:)`, `User.from_solana_wallet(addr)`), the relevant columns (`email`, `email_verified_at`, `solana_address`, optional `session_token`), and `default_url_options` for mailer link generation.
+
 ## v0.4.13 (2026-06-02)
 
 Promotes `components/_avatar_cropper` onto the shared crop-photo modal — completing the image-upload extraction started in v0.4.12. The avatar cropper is the **deferred-form-field** counterpart to `imageUploadHost`: it stages a cropped PNG on a hidden file input + shows a round preview, and the enclosing form (signup / profile edit) submits later (vs. `imageUploadHost`, which submits immediately).

data/app/controllers/concerns/solana/session_auth.rb

@@ -0,0 +1,55 @@
+module Solana
+  # Rails-session adapter around solana_studio's pure
+  # Solana::AuthVerifier.verify!. Lives under app/controllers/concerns/ as
+  # `Solana::SessionAuth` (NOT `Solana::AuthVerifier`) — the gem owns that
+  # latter namespace, and Zeitwerk autoload skips colliding constants. By
+  # keeping this concern under a distinct module name, both pieces of code
+  # load reliably.
+  #
+  # Controllers `include Solana::SessionAuth` and call
+  # `verify_solana_signature!(message:, signature_b58:, pubkey_b58:, session:)`.
+  # This shim pulls/deletes the nonce from session (delete-before-verify =
+  # replay protection) and delegates the cryptography to the gem.
+  #
+  # Errors raised by the gem (`Solana::AuthVerifier::VerificationError`) are
+  # passed through unwrapped — controllers rescue that gem-defined constant
+  # directly.
+  #
+  # The `solana-studio` gem is provided by the consuming app (both McRitchie
+  # Studio + Turf Monster bundle it); this concern is only ever included when
+  # wallet sign-in is enabled, so a wallet-less app never loads ::Solana::AuthVerifier.
+  #
+  # Lifted into studio-engine (was turf-monster app/controllers/concerns/solana/session_auth.rb).
+  module SessionAuth
+    extend ActiveSupport::Concern
+
+    def verify_solana_signature!(message:, signature_b58:, pubkey_b58:, session:, expected_user_id: nil)
+      # OPSEC-005: when the caller is authenticated, require the signed
+      # message to embed `User-ID: <current_user.id>` so a signature
+      # captured against a *different* session's nonce can't be replayed
+      # into this user's flow. Login (solana_sessions#verify) calls without
+      # expected_user_id since there's no current_user yet — the nonce
+      # delete-before-verify below remains replay protection for that path.
+      if expected_user_id && !message.to_s.include?("User-ID: #{expected_user_id}")
+        raise ::Solana::AuthVerifier::VerificationError,
+              "Signed message missing User-ID binding for current session"
+      end
+
+      # Delete nonce BEFORE verification to prevent replay
+      stored_nonce = session.delete(:solana_nonce)
+      nonce_at     = session.delete(:solana_nonce_at)
+
+      # OPSEC-018: bind the signature to this host. The client builds the
+      # message with `window.location.host`; request.host_with_port is the
+      # server-side equal (hostname, plus port only when non-default).
+      ::Solana::AuthVerifier.verify!(
+        message:       message,
+        signature_b58: signature_b58,
+        pubkey_b58:    pubkey_b58,
+        expected_host: request.host_with_port,
+        stored_nonce:  stored_nonce,
+        nonce_at:      nonce_at
+      )
+    end
+  end
+end

data/app/controllers/concerns/studio/error_handling.rb

@@ -8,7 +8,8 @@ module Studio
 
       before_action :require_authentication
 
-      helper_method :current_user, :logged_in?, :sso_user_available?, :sso_display_name, :sso_source_app, :sso_hub_logo, :admin?
+      helper_method :current_user, :logged_in?, :sso_user_available?, :sso_display_name, :sso_source_app, :sso_hub_logo, :admin?,
+                    :onchain_session?, :wallet_context, :client_session_payload
     end
 
     private
@@ -22,6 +23,25 @@ module Studio
       # App-specific session (only this app reads this key)
       session[Studio.session_key] = user.id
 
+      # OPSEC-045: bind a rotating per-user token into the cookie. The
+      # verify_session_token filter compares it to user.session_token on every
+      # request, so a server-side rotation (email change, "log out everywhere")
+      # invalidates stolen sessions. Guarded for consumers whose User has no
+      # session_token column. Backfills a blank token (legacy rows / fixtures
+      # predate the column) so they aren't force-logged-out on the next request.
+      if user.respond_to?(:session_token)
+        if user.session_token.blank? && user.respond_to?(:update_column)
+          user.update_column(:session_token, SecureRandom.hex(32))
+        end
+        session[:session_token] = user.session_token
+      end
+
+      # The on-chain-session flag is a Phantom-wallet-signature privilege.
+      # Reset it on every login so a stale flag from an earlier wallet session
+      # can't leak into a later email/Google login. SolanaSessionsController#verify
+      # re-grants it for genuine wallet auth.
+      session.delete(:onchain)
+
       # Only update shared awareness fields if this app is the source
       # (don't overwrite the other app's sso_source when logging in via sso_continue)
       if session[:sso_source].blank? || session[:sso_source] == Studio.app_name
@@ -37,6 +57,8 @@ module Studio
 
     def clear_app_session
       session.delete(Studio.session_key)
+      session.delete(:session_token)
+      session.delete(:onchain)
 
       # Clear sso_* fields only if this app is the source
       # (preserve them if the other app set them — they're still logged in there)
@@ -72,12 +94,72 @@ module Studio
       current_user.present?
     end
 
+    # Format-aware: a full-page HTML request gets the login redirect, but an
+    # AJAX/Turbo request gets a clean 401 (a blind redirect to the HTML login
+    # page makes Rails return 406 Not Acceptable for an `Accept: application/json`
+    # request — OPSEC-046). The JS fetch layer turns the 401 into a login modal.
     def require_authentication
-      unless logged_in?
-        redirect_to login_path
+      return if logged_in?
+
+      respond_to do |format|
+        format.html         { redirect_to login_path }
+        format.json         { render json: { error: "unauthenticated" }, status: :unauthorized }
+        format.turbo_stream { head :unauthorized }
+        format.any          { head :unauthorized }
       end
     end
 
+    # Populates Current.* for the request lifecycle so audit/logging layers can
+    # attribute work to the viewer without param threading. Best-effort —
+    # never breaks the request path. Apps wire this as a before_action.
+    def set_current_context
+      Current.user = current_user if logged_in?
+    rescue StandardError
+      nil
+    end
+
+    # OPSEC-045: enforce session-token binding. No-ops for consumers whose User
+    # has no session_token. Runs early (apps wire it as a before_action ahead of
+    # require_authentication) so a stale session is cleared before current_user
+    # is read downstream.
+    def verify_session_token
+      return unless logged_in?
+      return unless current_user.respond_to?(:session_token)
+
+      user_token   = current_user.session_token
+      cookie_token = session[:session_token]
+      return if user_token.present? && user_token == cookie_token
+
+      Rails.logger.info("[opsec-045] session_token mismatch user_id=#{current_user.id} — forcing re-login")
+      @current_user = nil
+      clear_app_session
+      respond_to do |format|
+        format.html { redirect_to login_path, alert: "Your session expired. Please sign in again." }
+        format.json { render json: { error: "session expired" }, status: :unauthorized }
+        format.any  { head :unauthorized }
+      end
+    end
+
+    # True when this session authenticated via a live Solana wallet signature
+    # (not email/Google). Set by SolanaSessionsController#verify.
+    def onchain_session?
+      session[:onchain] == true
+    end
+
+    # Canonical auth + wallet state for this request — the single source of truth
+    # the whole UI branches on (web3 / web2 / guest). Serialised into the page and
+    # mirrored client-side by Alpine.store('session'). See SessionContext.
+    def wallet_context
+      @wallet_context ||= SessionContext.new(user: current_user, onchain_session: onchain_session?)
+    end
+
+    # Payload serialised into #session-context for Alpine.store('session').
+    # Baseline = identity only (SessionContext stays RPC-free). Apps override to
+    # merge on-chain balances/tokens they already preloaded for the request.
+    def client_session_payload
+      wallet_context.to_h
+    end
+
     def require_admin
       return redirect_to root_path, alert: "Not authorized" unless logged_in? && current_user.admin?
     end

data/app/controllers/magic_links_controller.rb

@@ -0,0 +1,83 @@
+# 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
+#
+# 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
+# is safely logged in here and stamped email_verified_at (unlike from_omniauth,
+# which refuses that collision precisely because it lacked this proof).
+#
+# This is the engine's GENERIC base. Apps that need richer post-consume routing
+# (e.g. turf-monster's contest landing + picks rehydration + entry-tokens upsell)
+# OVERRIDE this controller in the app and reuse the MagicLink service + the
+# sign_in_existing / sign_up_new building blocks.
+class MagicLinksController < ApplicationController
+  skip_before_action :require_authentication
+
+  # 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
+  # enumerate. A malformed email gets the same response with no mail sent.
+  def create
+    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
+    end
+    respond_to do |format|
+      format.json { render json: { success: true } }
+      format.html { redirect_to login_path, notice: "Check your inbox — we just emailed you a sign-in link." }
+    end
+  end
+
+  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")
+    result = MagicLink.consume(params[:token])
+    user = User.find_by(email: result.email)
+    user ? sign_in_existing(user, result) : sign_up_new(result)
+  rescue MagicLink::InvalidToken
+    redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
+  end
+
+  private
+
+  def sign_in_existing(user, result)
+    set_app_session(user)
+    user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at) && user.email_verified_at.blank?
+    redirect_to(safe_path(result.return_to) || root_path, notice: "Signed in. Welcome back!")
+  end
+
+  # Build → configure_new_user → save!. There is no password — email auth is
+  # magic-link only (the password_digest column, if present, stays dormant).
+  def sign_up_new(result)
+    user = User.new(email: result.email)
+    Studio.configure_new_user.call(user)
+    rescue_and_log(target: user) do
+      user.save!
+      user.update!(email_verified_at: Time.current) if user.respond_to?(:email_verified_at)
+      set_app_session(user)
+      redirect_to(safe_path(result.return_to) || root_path, notice: Studio.welcome_message.call(user))
+    end
+  rescue ActiveRecord::RecordNotUnique
+    # Two valid tokens for the same brand-new email consumed near-simultaneously
+    # both miss find_by and race to save!; the loser hits the unique index.
+    # Benign — the account now exists, so just log the winner in.
+    existing = User.find_by(email: result.email)
+    return sign_in_existing(existing, result) if existing
+
+    redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
+  rescue StandardError => e
+    Rails.logger.error("[MagicLinksController#consume] signup failed #{e.class}: #{e.message}")
+    redirect_to login_path, alert: "We couldn't finish creating your account. Please try again."
+  end
+
+  def safe_path(path)
+    p = path.to_s
+    p.start_with?("/") && !p.start_with?("//") ? p : nil
+  end
+end

data/app/controllers/omniauth_callbacks_controller.rb

@@ -1,17 +1,46 @@
+# Google OAuth callback (the web2 social path).
+#
+# Defense-in-depth: omniauth-google-oauth2 already verifies the id_token's JWT
+# signature against Google's JWKS, but we additionally re-validate it server-side
+# via Google's tokeninfo endpoint (GoogleOauthValidator) to assert audience +
+# email_verified + expiry before trusting the identity. Only a Google-confirmed
+# verified email is allowed to find-or-create an account.
+#
+# Engine GENERIC base. turf-monster OVERRIDES this controller for popup-mode,
+# account merge, wallet-collision stashing, and funnel attribution.
 class OmniauthCallbacksController < ApplicationController
   skip_before_action :require_authentication
 
   def create
-    user = User.from_omniauth(request.env["omniauth.auth"])
+    auth = request.env["omniauth.auth"]
+    result = GoogleOauthValidator.new(id_token: id_token_from(auth)).validate!
+    unless result.ok?
+      Rails.logger.warn("[omniauth] google id_token rejected: #{result.reason}")
+      return redirect_to login_path, alert: "Google sign-in could not be verified. Please try again."
+    end
+
+    user = User.from_omniauth(auth, email_verified: result.email_verified)
+    unless user.is_a?(User)
+      return redirect_to login_path, alert: "Google sign-in couldn't be completed. Please try another method."
+    end
+
     rescue_and_log(target: user) do
       set_app_session(user)
       redirect_to root_path, notice: "Signed in with Google!"
     end
-  rescue StandardError => e
+  rescue StandardError
     redirect_to login_path, alert: "Google sign-in failed. Please try again."
   end
 
   def failure
     redirect_to login_path, alert: "Google sign-in failed. Please try again."
   end
+
+  private
+
+  # The id_token lives at auth.extra.id_token (OmniAuth AuthHash) — read it
+  # tolerantly so a missing extras hash (test mock) doesn't raise.
+  def id_token_from(auth)
+    auth&.dig("extra", "id_token") || (auth.respond_to?(:extra) ? auth.extra&.id_token : nil)
+  end
 end

data/app/controllers/registrations_controller.rb

@@ -6,6 +6,19 @@ class RegistrationsController < ApplicationController
   end
 
   def create
+    # Passwordless apps: there is no create-account-by-form. Logging a user in
+    # straight from a signup POST would skip proof of email ownership, so we
+    # treat "sign up" as a magic-link request — the create-or-login link (which
+    # only fires after the recipient clicks it) does the account creation.
+    unless Studio.auth_method?(:password)
+      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
+      end
+      return redirect_to login_path, notice: "Check your inbox — we just emailed you a sign-in link."
+    end
+
     @user = User.new(user_params)
     Studio.configure_new_user.call(@user)
     rescue_and_log(target: @user) do

data/app/controllers/solana_sessions_controller.rb

@@ -0,0 +1,52 @@
+# Solana / Phantom wallet sign-in (the web3 path).
+#
+#   GET  /auth/solana/nonce  — issue a one-time nonce for the SIWS message
+#   POST /auth/solana/verify — verify the ed25519 signature, log in / sign up
+#
+# The cryptography lives in the solana-studio gem (Solana::AuthVerifier); the
+# Solana::SessionAuth concern adapts it to the Rails session (delete-before-verify
+# nonce burn + host binding). On success the session is granted the :onchain flag
+# so SessionContext reports :web3 (can sign on-chain txs this session).
+#
+# Engine GENERIC base. Apps with a richer wallet identity (turf-monster: managed
+# wallets, web2/web3 address split, account-linking, referral attribution)
+# OVERRIDE this controller; it stays this simple for an app whose wallet is just
+# an identity (one `solana_address` column).
+class SolanaSessionsController < ApplicationController
+  include Solana::SessionAuth
+  skip_before_action :require_authentication
+
+  def nonce
+    session[:solana_nonce]    = SecureRandom.hex(16)
+    session[:solana_nonce_at] = Time.current.to_i
+    render json: { nonce: session[:solana_nonce] }
+  end
+
+  def verify
+    pubkey_b58 = verify_solana_signature!(
+      message:       params[:message],
+      signature_b58: params[:signature],
+      pubkey_b58:    params[:pubkey],
+      session:       session
+    )
+
+    user   = User.from_solana_wallet(pubkey_b58)
+    is_new = user.nil?
+
+    if is_new
+      user = User.new(solana_address: pubkey_b58)
+      Studio.configure_new_user.call(user)
+    end
+
+    rescue_and_log(target: user) do
+      user.save! if user.new_record?
+      set_app_session(user)
+      session[:onchain] = true
+      render json: { success: true, redirect: root_path, new_user: is_new }
+    end
+  rescue ::Solana::AuthVerifier::VerificationError => e
+    render json: { error: e.message }, status: :unauthorized
+  rescue StandardError => e
+    render json: { error: e.message }, status: :unprocessable_entity
+  end
+end

data/app/mailers/application_mailer.rb

@@ -0,0 +1,7 @@
+class ApplicationMailer < ActionMailer::Base
+  # Resolved per-message (proc default) so it picks up Studio.mailer_from set in
+  # the host's config/initializers/studio.rb, with an ENV fallback. No layout is
+  # forced — ActionMailer renders bare if the host ships no mailer layout, and a
+  # host that defines its own ApplicationMailer (e.g. turf-monster) wins outright.
+  default from: -> { Studio.mailer_from || ENV["MAILER_FROM"] || "no-reply@mcritchie.studio" }
+end

data/app/mailers/user_mailer.rb

@@ -0,0 +1,14 @@
+class UserMailer < ApplicationMailer
+  # Passwordless sign-in link. `email` is a raw string (the recipient may not
+  # have an account yet). Token is a signed MagicLink payload (email + return_to
+  # + jti, single-use). Clicking the link logs the recipient in or creates their
+  # account. App-name-aware so the same template serves every Studio app.
+  #
+  # Engine GENERIC base. An app needing richer copy (e.g. turf-monster's
+  # contest-aware variant) defines its own UserMailer, which wins.
+  def magic_link(email, token)
+    @app_name  = Studio.app_name
+    @magic_url = magic_link_url(token: token)
+    mail(to: email, subject: "Your #{@app_name} sign-in link")
+  end
+end

data/app/models/current.rb

@@ -0,0 +1,14 @@
+# Request- and job-scoped context. ActiveSupport::CurrentAttributes auto-resets
+# between requests (Rack middleware) and between Sidekiq/ActiveJob jobs.
+#
+#   - `Current.user` — set by the engine's set_current_context before_action so
+#     downstream code (loggers, audit) can attribute work to the viewer without
+#     threading params through every layer.
+#
+# Baseline shipped by studio-engine. Apps that need more request-scoped state
+# (e.g. turf-monster's `outbound_source` + admin vault-state memo) OVERRIDE this
+# whole file — the non-isolated engine lets the host's app/models/current.rb win,
+# and a subclass-style `attribute` list simply replaces this one.
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user
+end

data/app/models/session_context.rb

@@ -0,0 +1,85 @@
+# Canonical, single source of truth for the current viewer's auth + wallet state.
+#
+# `mode` is the 3-way value the entire UI branches on:
+#   :guest — not logged in
+#   :web2  — logged in with a custodial/managed wallet this session (email or
+#            Google login, or a Phantom account that did NOT authenticate via a
+#            wallet signature this session)
+#   :web3  — logged in AND authenticated via a live Phantom wallet signature
+#            this session (onchain_session?) — i.e. can sign on-chain txs now
+#
+# Mode is decided by the SESSION, not by account identity: a Phantom owner who
+# logs in by email is :web2 for that session. `phantom_linked?` exposes the
+# account-level fact separately, so the UI can still offer "Connect Phantom".
+#
+# Built once per request by ApplicationController#wallet_context, serialised
+# into the page, and mirrored client-side by Alpine.store('session').
+#
+# Lifted into studio-engine (was turf-monster app/models). Wallet predicates are
+# called through `respond_to?` so an app with wallet sign-in disabled (no
+# #phantom_wallet? / #solana_address on User) still gets correct :guest/:web2.
+class SessionContext
+  MODES = %i[guest web2 web3].freeze
+
+  attr_reader :user
+
+  def initialize(user:, onchain_session:)
+    @user = user
+    @onchain_session = onchain_session
+  end
+
+  # The canonical 3-way. Session-based — see class comment.
+  def mode
+    return :guest unless user
+    @onchain_session ? :web3 : :web2
+  end
+
+  def guest?
+    mode == :guest
+  end
+
+  def web2?
+    mode == :web2
+  end
+
+  def web3?
+    mode == :web3
+  end
+
+  def logged_in?
+    !guest?
+  end
+
+  # Account-level fact, independent of `mode`: the account holds a self-custody
+  # (Phantom) wallet. A :web2-mode session can still be phantom_linked — that is
+  # exactly the "Phantom owner logged in by email" case.
+  def phantom_linked?
+    (user.respond_to?(:phantom_wallet?) && user.phantom_wallet?) || false
+  end
+
+  def user_id
+    user&.id
+  end
+
+  # Primary wallet address (web3 preferred), or nil when logged out / wallet-less.
+  def address
+    return nil unless user.respond_to?(:solana_address)
+    user.solana_address
+  end
+
+  # Shape consumed by the client Alpine.store('session'). Kept deliberately
+  # cheap — DB/session columns only, never an on-chain RPC call.
+  def to_h
+    {
+      loggedIn:      logged_in?,
+      mode:          mode,
+      phantomLinked: phantom_linked?,
+      userId:        user_id,
+      address:       address.to_s
+    }
+  end
+
+  def as_json(*)
+    to_h
+  end
+end

data/app/services/google_oauth_validator.rb

@@ -0,0 +1,98 @@
+require "net/http"
+require "uri"
+require "json"
+
+# Server-side re-validation of a Google OAuth id_token via Google's tokeninfo
+# endpoint, mirroring the pattern of re-fetching from the provider's API rather
+# than trusting omniauth's parsed payload.
+#
+# The omniauth-google-oauth2 gem already verifies the JWT signature against
+# Google's JWKS, so this is defense-in-depth — primarily it ensures:
+#   1. The id_token's audience matches GOOGLE_CLIENT_ID (correct app)
+#   2. email_verified is `true` per Google's own claim (closes the silent
+#      from_omniauth find-by-email link if Google hasn't confirmed the email)
+#   3. The token isn't expired by Google's clock
+#
+# Usage:
+#   result = GoogleOauthValidator.new(id_token: auth.extra.id_token).validate!
+#   if result.ok?
+#     # safe to use result.email, result.email_verified
+#   else
+#     # logging + reject
+#   end
+#
+# Lifted into studio-engine (was turf-monster app/services/google_oauth_validator.rb).
+class GoogleOauthValidator
+  TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo".freeze
+  NET_TIMEOUT_SECONDS = 5
+
+  Result = Struct.new(:ok, :email, :email_verified, :reason, keyword_init: true) do
+    def ok?
+      ok == true
+    end
+  end
+
+  def initialize(id_token:, expected_aud: ENV["GOOGLE_CLIENT_ID"])
+    @id_token = id_token
+    @expected_aud = expected_aud
+  end
+
+  def validate!
+    # Test-mode affordance: OmniAuth.config.test_mode replaces the real
+    # OAuth flow with mock_auth, which doesn't carry a real id_token. The
+    # gem already verifies the mock signature/state internally; this
+    # validator has nothing real to re-check.
+    #
+    # We bypass on `OmniAuth.config.test_mode` (NOT just Rails.env.test?)
+    # because Playwright can run the e2e suite against a DEV server, and
+    # test_mode is the canonical "we are in a mock OAuth flow" signal.
+    # Production NEVER enables test_mode, so this widens the test surface
+    # without weakening the production guard.
+    test_mode = (defined?(OmniAuth) && OmniAuth.config.respond_to?(:test_mode) && OmniAuth.config.test_mode)
+    return Result.new(ok: true, email: nil, email_verified: true, reason: :test_skip) if @id_token.blank? && (Rails.env.test? || test_mode)
+
+    return Result.new(ok: false, reason: :missing_id_token) if @id_token.blank?
+    return Result.new(ok: false, reason: :missing_expected_aud) if @expected_aud.blank?
+
+    response = fetch_tokeninfo
+    return Result.new(ok: false, reason: :tokeninfo_unreachable) unless response
+
+    if response.code.to_i != 200
+      return Result.new(ok: false, reason: :tokeninfo_rejected)
+    end
+
+    body = JSON.parse(response.body) rescue nil
+    return Result.new(ok: false, reason: :tokeninfo_parse_failed) unless body
+
+    # `email_verified` is a string "true"/"false" in tokeninfo responses.
+    email_verified = body["email_verified"].to_s == "true"
+
+    unless body["aud"] == @expected_aud
+      return Result.new(ok: false, email: body["email"], email_verified: email_verified, reason: :wrong_audience)
+    end
+
+    unless email_verified
+      return Result.new(ok: false, email: body["email"], email_verified: false, reason: :email_not_verified)
+    end
+
+    expiry = body["exp"].to_i
+    if expiry > 0 && expiry < Time.current.to_i
+      return Result.new(ok: false, email: body["email"], email_verified: true, reason: :expired)
+    end
+
+    Result.new(ok: true, email: body["email"], email_verified: true, reason: nil)
+  end
+
+  private
+
+  def fetch_tokeninfo
+    uri = URI(TOKENINFO_URL)
+    uri.query = URI.encode_www_form(id_token: @id_token)
+    Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: NET_TIMEOUT_SECONDS, read_timeout: NET_TIMEOUT_SECONDS) do |http|
+      http.request(Net::HTTP::Get.new(uri.request_uri))
+    end
+  rescue StandardError => e
+    Rails.logger.warn("[GoogleOauthValidator] tokeninfo fetch failed: #{e.class}: #{e.message}")
+    nil
+  end
+end

data/app/services/magic_link.rb

@@ -0,0 +1,115 @@
+# Unified create-or-login magic link.
+#
+# A magic link is a signed, short-lived, single-use token keyed on an EMAIL
+# (the user may not exist yet — clicking the link either logs them in or
+# creates the account). The token is a `message_verifier(token_name)` payload
+# carrying the email + a sanitized return_to + a random jti.
+#
+# Single-use is enforced with the jti: on `generate` we record the jti in
+# Rails.cache (Redis, cross-process); on `consume` we delete it and reject if
+# it was already gone (replay / second click). The signature already covers
+# tamper + expiry; the jti closes the replay gap.
+#
+# Token name + TTL come from Studio config (Studio.magic_link_token_name /
+# Studio.magic_link_ttl) so each app can tune them; the jti cache entry is
+# always given a few extra minutes so a still-valid token's jti is present.
+#
+# NOTE on test env: the test cache is :null_store, where writes/deletes are
+# no-ops and `delete` always returns false — enforcing single-use there would
+# reject every legitimate consume. So enforcement is skipped for non-tracking
+# stores; the service unit test injects a real MemoryStore to exercise it.
+#
+# Lifted into studio-engine (was turf-monster app/services/magic_link.rb).
+class MagicLink
+  class InvalidToken < StandardError; end
+
+  Result = Struct.new(:email, :return_to, keyword_init: true)
+
+  class << self
+    # Test seam — defaults to Rails.cache. The service unit test sets this to
+    # an ActiveSupport::Cache::MemoryStore to assert single-use, then resets it.
+    attr_writer :cache
+
+    def cache
+      @cache || Rails.cache
+    end
+
+    def token_name
+      Studio.magic_link_token_name
+    end
+
+    def ttl
+      Studio.magic_link_ttl
+    end
+
+    # jti outlives the token so a valid token's jti is always still present.
+    def jti_ttl
+      ttl + 5.minutes
+    end
+
+    # Returns a signed token string. `return_to` is sanitized to a local path.
+    # The MessageVerifier blob is standard base64 (can contain "/" and "+"),
+    # which breaks the `%r{[^/]+}` route constraint once the payload is large
+    # enough to emit a "/". Wrap it URL-safe so the token is always
+    # [A-Za-z0-9_-]=, matching the route and surviving URL generation.
+    def generate(email:, return_to: nil)
+      normalized = normalize_email(email)
+      jti = SecureRandom.hex(16)
+      cache.write(jti_key(jti), normalized, expires_in: jti_ttl) if enforce_single_use?
+      raw = verifier.generate(
+        { email: normalized, return_to: sanitize_path(return_to), jti: jti, v: 1 },
+        expires_in: ttl
+      )
+      Base64.urlsafe_encode64(raw)
+    end
+
+    # Verifies signature + expiry + single-use. Returns a Result or raises
+    # InvalidToken. Idempotency is NOT offered — a consumed token is dead.
+    def consume(token)
+      raw = Base64.urlsafe_decode64(token.to_s)
+      payload = verifier.verify(raw).with_indifferent_access
+      raise InvalidToken, "unexpected token shape" unless payload[:v] == 1 && payload[:email].present?
+
+      if enforce_single_use?
+        # delete returns true only when the jti was still present
+        raise InvalidToken, "link already used or expired" unless cache.delete(jti_key(payload[:jti]))
+      elsif !Rails.env.test?
+        # Single-use is disabled (non-tracking cache). Expected in :null_store
+        # dev; in any other env it means replay protection is silently OFF —
+        # tokens are replayable for their TTL. Surface it loudly.
+        Rails.logger.warn("[MagicLink] single-use NOT enforced (cache=#{cache.class}); links are replayable until expiry")
+      end
+
+      Result.new(email: payload[:email], return_to: sanitize_path(payload[:return_to]))
+    rescue ActiveSupport::MessageVerifier::InvalidSignature, ArgumentError
+      # ArgumentError → malformed base64 (tampered/truncated token).
+      raise InvalidToken, "invalid or expired link"
+    end
+
+    private
+
+    def verifier
+      Rails.application.message_verifier(token_name)
+    end
+
+    def jti_key(jti)
+      "magic_link/jti/#{jti}"
+    end
+
+    def normalize_email(email)
+      email.to_s.strip.downcase
+    end
+
+    # Only same-origin absolute paths survive; everything else (protocol-relative
+    # "//evil", absolute URLs, blank) collapses to nil so callers fall back to a
+    # default redirect.
+    def sanitize_path(path)
+      p = path.to_s
+      p.start_with?("/") && !p.start_with?("//") ? p : nil
+    end
+
+    def enforce_single_use?
+      !cache.is_a?(ActiveSupport::Cache::NullStore)
+    end
+  end
+end

data/app/views/user_mailer/magic_link.html.erb

@@ -0,0 +1,14 @@
+<h1>Your sign-in link</h1>
+
+<p>Tap the button below to sign in to <%= @app_name %>. If you don't have an
+   account yet, we'll create one for you — no password needed:</p>
+
+<p><%= link_to "Sign in to #{@app_name}", @magic_url %></p>
+
+<p>If the button doesn't work, copy and paste this URL into your browser:</p>
+<p><%= @magic_url %></p>
+
+<p>Open this link on this device to finish. It expires shortly and can only be
+   used once. If you didn't request it, you can safely ignore this message.</p>
+
+<p>— <%= @app_name %></p>

data/app/views/user_mailer/magic_link.text.erb

@@ -0,0 +1,9 @@
+Open this link to sign in to <%= @app_name %>. If you don't have an account yet,
+we'll create one for you — no password needed:
+
+<%= @magic_url %>
+
+Open this link on this device to finish. It expires shortly and can only be
+used once. If you didn't request it, you can safely ignore this message.
+
+— <%= @app_name %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.4.13"
+  VERSION = "0.5.0"
 end

data/lib/studio.rb

@@ -16,6 +16,23 @@ module Studio
   mattr_accessor :sso_logo,            default: nil
   mattr_accessor :theme_logos,         default: []
 
+  # ---- Authentication ------------------------------------------------------
+  # Which sign-in methods this app offers. The shared login/signup views render
+  # a button/field per enabled method (gate with Studio.auth_method?). Order is
+  # display order. Both McRitchie Studio + Turf Monster are passwordless; legacy
+  # email+password is opt-in via :password (which also re-arms the User#authenticate
+  # contract check — see validate_user_contract!).
+  mattr_accessor :auth_methods, default: %i[magic_link google wallet]
+
+  # Magic-link (passwordless email) tuning. token_name keys the MessageVerifier
+  # purpose; bump it to invalidate every outstanding link. See MagicLink service.
+  mattr_accessor :magic_link_ttl,        default: 15.minutes
+  mattr_accessor :magic_link_token_name, default: "magic_link_v1"
+
+  # Default From: for engine-sent mail (magic links). Apps set this to their
+  # verified Resend sending address in config/initializers/studio.rb.
+  mattr_accessor :mailer_from, default: nil
+
   # Theme role colors (7 roles)
   mattr_accessor :theme_primary,  default: "#8E82FE"
   mattr_accessor :theme_dark,     default: "#1A1535"
@@ -46,8 +63,11 @@ module Studio
   # ActiveRecord defines them lazily — they don't appear on `.instance_methods`
   # until the schema is introspected (typically first record access). Missing
   # columns are caught by the User table schema, not by this validator.
-  REQUIRED_USER_INSTANCE_METHODS = %i[authenticate admin? display_name].freeze
+  REQUIRED_USER_INSTANCE_METHODS = %i[admin? display_name].freeze
   REQUIRED_USER_CLASS_METHODS    = %i[find_by].freeze
+  # #authenticate is only required when email+password sign-in is enabled.
+  # Passwordless apps (the default) never call it.
+  PASSWORD_USER_INSTANCE_METHODS = %i[authenticate].freeze
 
   class UserContractError < StandardError; end
 
@@ -55,6 +75,11 @@ module Studio
     yield self
   end
 
+  # True when the given sign-in method is enabled for this app.
+  def self.auth_method?(method)
+    auth_methods.include?(method.to_sym)
+  end
+
   # Verifies that the host app's User model satisfies the engine's expected
   # contract. Raises Studio::UserContractError with a clear pointer to
   # docs/USER_CONTRACT.md if anything required is missing. Called from
@@ -67,7 +92,9 @@ module Studio
     REQUIRED_USER_CLASS_METHODS.each do |m|
       missing << "User.#{m}" unless user_class.respond_to?(m)
     end
-    REQUIRED_USER_INSTANCE_METHODS.each do |m|
+    instance_methods = REQUIRED_USER_INSTANCE_METHODS.dup
+    instance_methods.concat(PASSWORD_USER_INSTANCE_METHODS) if auth_method?(:password)
+    instance_methods.each do |m|
       missing << "User##{m}" unless user_class.instance_methods.include?(m)
     end
 
@@ -122,6 +149,26 @@ module Studio
       post "signup", to: "registrations#create"
       get  "auth/:provider/callback", to: "omniauth_callbacks#create"
       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.
+      if 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,
+             constraints: { token: %r{[^/]+} }
+      end
+
+      # Solana / Phantom wallet sign-in (nonce challenge + signature verify).
+      # The browser posts to these literal paths from the shared Connect-Wallet
+      # flow; app-specific surfaces (mobile deep-link callback, account-linking,
+      # OAuth popup) stay in the consuming app's routes.
+      if Studio.auth_method?(:wallet)
+        get  "auth/solana/nonce",  to: "solana_sessions#nonce",  as: :solana_nonce
+        post "auth/solana/verify", to: "solana_sessions#verify", as: :solana_verify
+      end
+
       resources :error_logs, only: [:index, :show]
 
       # Admin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.4.13
+  version: 0.5.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -108,20 +108,29 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- app/controllers/concerns/solana/session_auth.rb
 - app/controllers/concerns/studio/error_handling.rb
 - app/controllers/error_logs_controller.rb
+- app/controllers/magic_links_controller.rb
 - app/controllers/navbar_controller.rb
 - app/controllers/omniauth_callbacks_controller.rb
 - app/controllers/registrations_controller.rb
 - app/controllers/schema_controller.rb
 - app/controllers/sessions_controller.rb
+- app/controllers/solana_sessions_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
+- app/mailers/application_mailer.rb
+- app/mailers/user_mailer.rb
 - app/models/concerns/sluggable.rb
+- app/models/current.rb
 - app/models/error_log.rb
 - app/models/image_cache.rb
+- app/models/session_context.rb
 - app/models/theme_setting.rb
+- app/services/google_oauth_validator.rb
+- app/services/magic_link.rb
 - app/views/components/_admin_dropdown.html.erb
 - app/views/components/_avatar.html.erb
 - app/views/components/_avatar_cropper.html.erb
@@ -156,6 +165,8 @@ files:
 - app/views/studio/modals/blocks/_progress_countdown.html.erb
 - app/views/studio/modals/blocks/_success_card.html.erb
 - app/views/theme_settings/edit.html.erb
+- app/views/user_mailer/magic_link.html.erb
+- app/views/user_mailer/magic_link.text.erb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/color_scale.rb