studio-engine 0.29.1 → 0.31.0

data/lib/studio.rb

@@ -1,12 +1,15 @@
 require "studio/version"
 require "studio/engine"
 require "studio/color_scale"
+require "studio/environment_banner"
 require "studio/theme_resolver"
 require "studio/ui_primitives"
+require "studio/sidebar_sections"
 require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
 require "studio/link_token"
+require "studio/link_resolution"
 require "studio/email"
 require "studio/email_smoke"
 require "studio/mail_transport"
@@ -61,18 +64,57 @@ module Studio
   # feature off (e.g. McRitchie Studio, which ships neither).
   mattr_accessor :features, default: []
 
-  # 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
+  # ---- Sidebar navigation ----
+  # Out-of-the-box navigation: the engine navbar mounts a link-sidebar trigger
+  # and slide-out panel when the host declares sections here. The default []
+  # renders NOTHING, so existing consumers see no change on upgrade until they
+  # opt in. Accepts a static Array of section hashes or a callable (receives
+  # the view context) for dynamic sections — route helpers, logged_in? walls.
+  # Sections flagged admin: true render only for admin? viewers. Shape and
+  # resolution rules: lib/studio/sidebar_sections.rb.
+  #
+  #   Studio.configure do |config|
+  #     config.sidebar_sections = ->(view) {
+  #       [ { title: "Site", links: [
+  #             { label: "Home", href: view.root_path, emoji: "🏠" } ] } ]
+  #     }
+  #   end
+  mattr_accessor :sidebar_sections, default: []
+
+  # How long a freshly minted magic link stays live.
+  mattr_accessor :magic_link_ttl, default: 15.minutes
+
+  # RETIRED (0.31.0) — kept only so an initializer that still sets it boots.
+  # It named the MessageVerifier purpose for the old :signed store, which no
+  # longer exists. Delete the line from your initializer.
   mattr_accessor :magic_link_token_name, default: "magic_link_v1"
 
-  # Where magic-link tokens are stored / which URL scheme they use.
-  #   :signed   (default) — stateless MessageVerifier MagicLink service; URL is
-  #             /magic_link/<long token>. No table needed. Back-compat default.
-  #   :database — a Studio::Link row; URL is the short /l/<token>. Requires the
-  #             studio_links table (install the reference migration). The
-  #             unified scheme both apps move to.
-  mattr_accessor :magic_link_store, default: :signed
+  # RETIRED (0.31.0) — magic links are ALWAYS Studio::Link rows now, so this
+  # reads :database and nothing else. Assigning :signed raises rather than
+  # silently downgrading: that store minted a ~350-character MessageVerifier
+  # blob whose EXPIRED form cannot be decoded, so an app on it could not tell
+  # whose dead link it was holding — which is exactly the fact
+  # Studio::LinkResolution needs to leave a live session alone. Requires the
+  # studio_links table, installed by `bin/rails studio_engine:install:migrations`
+  # (never hand-copied — a hand copy collides with the task's own copy on
+  # `class CreateStudioLinks`).
+  mattr_reader :magic_link_store, default: :database
+
+  # `to_s.to_sym`, not `to_sym`: this runs from an initializer, and nil or an
+  # Integer would raise NoMethodError — swallowing the explanation below with a
+  # message that says nothing about what to do. A blank falls through to the
+  # raise instead, so the operator reads the actual instruction.
+  def self.magic_link_store=(value)
+    return if value.to_s.to_sym == :database
+
+    raise ArgumentError,
+          "Studio.magic_link_store = #{value.inspect} is retired (studio-engine 0.31.0). " \
+          "Magic links are Studio::Link rows served at /l/<token>. Delete this line from " \
+          "config/initializers/studio.rb, then install the table with " \
+          "`bin/rails studio_engine:install:migrations && bin/rails db:migrate` — in that " \
+          "order, because this raise fires while the initializer loads and no rake task can " \
+          "boot until the line is gone."
+  end
 
   # Whether Studio.routes draws the magic_link + solana wallet routes. An app that
   # already defines its own auth routes (e.g. turf-monster, which has battle-tested
@@ -210,13 +252,13 @@ module Studio
     false
   end
 
-  # True when the emailed/inbox magic-link URL is the short /l/<token> — i.e.
-  # magic links are Studio::Link rows AND this app draws the /l routes. False =
-  # the legacy /magic_link/<token> path: the :signed store, OR an app on the
-  # :database store that keeps its own /magic_link route (e.g. turf-monster,
-  # whose /l is already its landing-page namespace).
+  # True when the emailed/inbox magic-link URL is the short /l/<token> — the
+  # standard. False means this app draws its own token route instead and owns
+  # the matching consume: turf-monster keeps /magic_link/<token> because /l is
+  # already its landing-page namespace. Either way the TOKEN is the same short
+  # Studio::Link token; only the path in front of it differs.
   def self.magic_link_via_l_route?
-    magic_link_store == :database && draw_link_routes
+    draw_link_routes
   end
 
   # The floor every developer-desk tool sits on: the local email inbox
@@ -238,6 +280,40 @@ module Studio
     env_truthy?(ENV["LOCAL_EMAIL_CAPTURE"]) || env_truthy?(ENV["AGENT_WORKTREE"])
   end
 
+  # ---- Shared environment banner ------------------------------------------
+  # Rules live in Studio::EnvironmentBanner (pure Ruby, unit-tested); these are
+  # the Rails-aware entry points `studio/banners/_environment` calls. A host
+  # renders that ONE partial instead of hand-rolling its own strip.
+
+  # True for a stable QA app: Rails-production, but a non-production review
+  # target that must identify itself as one. Keyed off QA_ENV, the signal the
+  # release conductor already sets on every QA app.
+  def self.qa_environment?
+    EnvironmentBanner.qa_environment?
+  end
+
+  def self.show_environment_banner?(rails_env: rails_env_name)
+    EnvironmentBanner.show?(rails_env: rails_env, qa_environment: qa_environment?)
+  end
+
+  def self.environment_banner_message(rails_env: rails_env_name, extra: [])
+    EnvironmentBanner.message(rails_env: rails_env, qa_environment: qa_environment?, extra: extra)
+  end
+
+  # Whether the local email inbox is actually REACHABLE for this request, which
+  # is the only honest reason to render a link to it. Deliberately the same
+  # gate the controller enforces (local_tool_enabled?), so the banner can never
+  # advertise a page that answers 404 — QA gets a status chip instead.
+  def self.local_inbox_reachable?(request_local:)
+    local_tool_enabled?(request_local: request_local)
+  end
+
+  def self.rails_env_name
+    return "development" unless defined?(Rails) && Rails.respond_to?(:env)
+
+    Rails.env.to_s
+  end
+
   def self.user_wallet_address(user)
     return nil unless user
 
@@ -278,7 +354,7 @@ module Studio
 
       See the USER_CONTRACT.md doc in the studio-engine repo for the full
       contract + a minimal compliant example:
-        https://github.com/amcritchie/studio-engine/blob/main/docs/USER_CONTRACT.md
+        https://github.com/McRitchie-Studio/studio-engine/blob/main/docs/USER_CONTRACT.md
 
       To bypass this check temporarily, set Studio.validate_user_contract = false
       in config/initializers/studio.rb.
@@ -309,6 +385,13 @@ module Studio
     entry ? "/#{entry[:file]}" : nil
   end
 
+  # Sidebar sections resolved for a view context: a callable config is called
+  # with the view, keys symbolize, and admin-only sections drop for non-admin
+  # viewers. Rendering gates on `.any?`, so [] keeps the navbar untouched.
+  def self.sidebar_sections_for(view)
+    SidebarSections.resolve(sidebar_sections, view)
+  end
+
   def self.env_truthy?(value)
     %w[1 true yes on].include?(value.to_s.strip.downcase)
   end
@@ -333,18 +416,15 @@ module Studio
         get "_studio/local_review", to: "studio/local_reviews#show",  as: :studio_local_review
       end
 
-      # Passwordless email (magic link). Helpers: magic_link_request_path (POST
-      # to request a link), magic_link_path(token) / magic_link_url(token:)
-      # for the emailed GET confirmation page, and magic_link_consume_path(token)
-      # for the scanner-safe POST consume. The token is a URL-safe
-      # MessageVerifier blob but the constraint guards against a stray "."
-      # segment.
+      # Passwordless email (magic link) — the REQUEST half only. Helper:
+      # magic_link_request_path (POST an email address, get a link mailed).
+      #
+      # The token-bearing half moved to /l/<token> below (0.31.0). There is one
+      # token format now — a short Studio::Link row — and one place that burns
+      # it, so the old /magic_link/:token confirm+consume pair would have been a
+      # second door onto the same lock.
       if Studio.draw_auth_routes && Studio.auth_method?(:magic_link)
-        post "magic_link",        to: "magic_links#create",   as: :magic_link_request
-        get  "magic_link/:token", to: "magic_links#confirm",  as: :magic_link,
-             constraints: { token: %r{[^/]+} }
-        post "magic_link/:token", to: "magic_links#consume",  as: :magic_link_consume,
-             constraints: { token: %r{[^/]+} }
+        post "magic_link", to: "magic_links#create", as: :magic_link_request
       end
 
       # Unified short-token links — /l/<token> for magic sign-in links + referral

data/studio-engine.gemspec

@@ -7,15 +7,15 @@ Gem::Specification.new do |spec|
   spec.email       = ["studio-engine@mcritchie.studio"]
   spec.summary     = "Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed image caching"
   spec.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 ImageCache. Used in production across the McRitchie Studio + Turf Monster apps."
-  spec.homepage    = "https://github.com/amcritchie/studio-engine"
+  spec.homepage    = "https://github.com/McRitchie-Studio/studio-engine"
   spec.license     = "MIT"
   spec.required_ruby_version = ">= 3.0"
 
   spec.metadata = {
-    "homepage_uri"    => "https://github.com/amcritchie/studio-engine",
-    "source_code_uri" => "https://github.com/amcritchie/studio-engine/tree/main",
-    "bug_tracker_uri" => "https://github.com/amcritchie/studio-engine/issues",
-    "changelog_uri"   => "https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md"
+    "homepage_uri"    => "https://github.com/McRitchie-Studio/studio-engine",
+    "source_code_uri" => "https://github.com/McRitchie-Studio/studio-engine/tree/main",
+    "bug_tracker_uri" => "https://github.com/McRitchie-Studio/studio-engine/issues",
+    "changelog_uri"   => "https://github.com/McRitchie-Studio/studio-engine/blob/main/CHANGELOG.md"
   }
 
   spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "db/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.29.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -201,6 +201,7 @@ files:
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
+- app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
 - app/jobs/studio/email_delivery_job.rb
@@ -219,7 +220,6 @@ files:
 - app/models/studio/model_page.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
-- app/services/magic_link.rb
 - app/services/studio/email_image.rb
 - app/views/components/_admin_dropdown.html.erb
 - app/views/components/_avatar.html.erb
@@ -232,7 +232,10 @@ files:
 - app/views/components/_google_logo.html.erb
 - app/views/components/_input.html.erb
 - app/views/components/_json_debug.html.erb
+- app/views/components/_link_sidebar.html.erb
+- app/views/components/_link_sidebar_trigger.html.erb
 - app/views/components/_progress_bar.html.erb
+- app/views/components/_sidebar_panel.html.erb
 - app/views/components/_theme_toggle.html.erb
 - app/views/components/_theme_toggle_morph.html.erb
 - app/views/components/_user_nav.html.erb
@@ -243,7 +246,6 @@ files:
 - app/views/layouts/studio/_flash.html.erb
 - app/views/layouts/studio/_head.html.erb
 - app/views/layouts/studio/_smooth_load.html.erb
-- app/views/magic_links/confirm.html.erb
 - app/views/navbar/show.html.erb
 - app/views/registrations/new.html.erb
 - app/views/schema/index.html.erb
@@ -330,11 +332,14 @@ files:
 - lib/studio/email.rb
 - lib/studio/email_smoke.rb
 - lib/studio/engine.rb
+- lib/studio/environment_banner.rb
 - lib/studio/image_cache.rb
+- lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
 - lib/studio/mail_transport.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb
+- lib/studio/sidebar_sections.rb
 - lib/studio/theme_resolver.rb
 - lib/studio/ui_primitives.rb
 - lib/studio/username_generator.rb
@@ -343,14 +348,14 @@ files:
 - lib/tasks/studio_ses.rake
 - studio-engine.gemspec
 - tailwind/studio.tailwind.config.js
-homepage: https://github.com/amcritchie/studio-engine
+homepage: https://github.com/McRitchie-Studio/studio-engine
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/amcritchie/studio-engine
-  source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
-  bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
-  changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/McRitchie-Studio/studio-engine
+  source_code_uri: https://github.com/McRitchie-Studio/studio-engine/tree/main
+  bug_tracker_uri: https://github.com/McRitchie-Studio/studio-engine/issues
+  changelog_uri: https://github.com/McRitchie-Studio/studio-engine/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:

data/app/services/magic_link.rb

@@ -1,122 +0,0 @@
-# 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
-  # Back-compat defaults. Behavior is driven by the `token_name` / `ttl` methods
-  # (which read Studio config); these constants remain so existing consumer code
-  # /tests referencing MagicLink::TTL keep working, and they equal the config
-  # defaults.
-  TOKEN_KEY = "magic_link_v1"
-  TTL       = 15.minutes
-
-  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/magic_links/confirm.html.erb

@@ -1,2 +0,0 @@
-<%# Legacy /magic_link/:token interstitial. Shared body in studio/_confirm_interstitial. %>
-<%= render "studio/confirm_interstitial", consume_path: magic_link_consume_path(token: @token) %>