studio-engine 0.4.1

data/lib/studio/image_cache.rb

@@ -0,0 +1,152 @@
+module Studio
+  module ImageCache
+    EXT_BY_TYPE = {
+      "image/png"  => "png",
+      "image/jpeg" => "jpg",
+      "image/jpg"  => "jpg",
+      "image/webp" => "webp",
+      "image/gif"  => "gif"
+    }.freeze
+
+    ALLOWED_CONTENT_TYPES = EXT_BY_TYPE.keys.freeze
+
+    # Per-call cap on the bytes we'll fetch from a remote source_url. 50MB
+    # covers high-res photos comfortably; anything larger should be uploaded
+    # via source_path (local file) to bypass this cap intentionally.
+    MAX_REMOTE_BYTES = 50 * 1024 * 1024
+
+    class InvalidSourceURL < ArgumentError; end
+    class UnsupportedContentType < ArgumentError; end
+    class SourceTooLarge < StandardError; end
+
+    # Caches an image at S3 under a folder per owner. Every call stores the
+    # unmodified source as variant "original", plus one resized variant per
+    # entry in widths.
+    #
+    # Layout:
+    #   {key_prefix}/original.{ext}
+    #   {key_prefix}/{width}.{ext}
+    #
+    # Source: provide EITHER source_url (HTTP fetch) OR source_path (local
+    # file). source_url is recorded on each ImageCache row regardless — for
+    # source_path callers, pass the original URL too if you want it tracked.
+    #
+    # source_url is validated against SSRF: scheme must be http/https,
+    # host must not be loopback/private/link-local/metadata-IP, and
+    # well-known internal hostnames (localhost, *.local, *.internal) are
+    # rejected. This does NOT defend against DNS rebinding — strong
+    # protection there requires resolving DNS once then passing the
+    # resolved IP to the HTTP client.
+    #
+    # Idempotent: variants already present in ImageCache are skipped. If
+    # nothing is missing, the source is never read.
+    def self.cache!(owner:, purpose:, key_prefix:, widths:, source_url: nil, source_path: nil, content_type: "image/png")
+      raise ArgumentError, "either source_url or source_path is required" if source_url.nil? && source_path.nil?
+
+      unless ALLOWED_CONTENT_TYPES.include?(content_type)
+        raise UnsupportedContentType, "content_type #{content_type.inspect} not in allowlist (#{ALLOWED_CONTENT_TYPES.join(", ")})"
+      end
+
+      validate_source_url!(source_url) if source_url
+
+      ext = EXT_BY_TYPE[content_type]
+      requested = ["original", *widths.map(&:to_s)]
+
+      existing = ::ImageCache.where(owner: owner, purpose: purpose).index_by(&:variant)
+      missing  = requested - existing.keys
+      return existing if missing.empty?
+
+      require "mini_magick"
+
+      body = if source_path
+        File.binread(source_path)
+      else
+        fetch_remote(source_url)
+      end
+
+      missing.each do |variant|
+        if variant == "original"
+          payload = body
+          s3_key  = "#{key_prefix}/original.#{ext}"
+        else
+          img = MiniMagick::Image.read(body)
+          # Cap ImageMagick resources per-invocation to prevent decompression-bomb DoS.
+          img.combine_options do |c|
+            c.limit "memory", "256MB"
+            c.limit "map", "512MB"
+            c.limit "width", "16KP"   # 16k pixel max width
+            c.limit "height", "16KP"
+            c.resize "#{variant}x"
+          end
+          payload = img.to_blob
+          s3_key  = "#{key_prefix}/#{variant}.#{ext}"
+        end
+
+        Studio::S3.upload(
+          key: s3_key,
+          body: payload,
+          content_type: content_type,
+          cache_control: "public, max-age=31536000, immutable"
+        )
+
+        existing[variant] = ::ImageCache.create!(
+          owner: owner,
+          purpose: purpose,
+          variant: variant,
+          s3_key: s3_key,
+          source_url: source_url,
+          bytes: payload.bytesize,
+          content_type: content_type
+        )
+      end
+
+      existing
+    end
+
+    # SSRF guard for remote source_url. Raises InvalidSourceURL on anything
+    # that looks like an attempt to reach internal services.
+    def self.validate_source_url!(url)
+      require "uri"
+      uri = URI.parse(url)
+      unless %w[http https].include?(uri.scheme)
+        raise InvalidSourceURL, "URL scheme must be http or https, got #{uri.scheme.inspect}"
+      end
+
+      host = uri.host.to_s.downcase
+      raise InvalidSourceURL, "URL missing host: #{url.inspect}" if host.empty?
+
+      # Hostname-based blocklist (catches common internal hostnames before any DNS).
+      if host == "localhost" || host.end_with?(".local") || host.end_with?(".internal") || host.end_with?(".lan")
+        raise InvalidSourceURL, "URL points to internal hostname: #{host.inspect}"
+      end
+
+      # If the host is a literal IP address, check ranges.
+      bracketed = host.start_with?("[") && host.end_with?("]")
+      ip_host = bracketed ? host[1..-2] : host
+      ipv4_like = ip_host.match?(/\A\d{1,3}(\.\d{1,3}){3}\z/)
+      ipv6_like = bracketed || ip_host.include?(":")
+      if ipv4_like || ipv6_like
+        require "ipaddr"
+        begin
+          ip = IPAddr.new(ip_host)
+        rescue IPAddr::Error => e
+          raise InvalidSourceURL, "Malformed IP host #{ip_host.inspect}: #{e.message}"
+        end
+        if ip.loopback? || ip.private? || ip.link_local? || ip_host == "169.254.169.254" || ip.to_s == "0.0.0.0" || ip.to_s == "::"
+          raise InvalidSourceURL, "URL points to internal/private IP: #{ip_host}"
+        end
+      end
+
+      uri
+    end
+
+    def self.fetch_remote(source_url)
+      require "open-uri"
+      body = URI.open(source_url, read_timeout: 30, redirect: true).read
+      if body.bytesize > MAX_REMOTE_BYTES
+        raise SourceTooLarge, "remote payload #{body.bytesize} bytes exceeds cap #{MAX_REMOTE_BYTES}"
+      end
+      body
+    end
+  end
+end

data/lib/studio/s3.rb

@@ -0,0 +1,72 @@
+module Studio
+  module S3
+    class Error < StandardError; end
+    class NotConfigured < Error; end
+
+    class << self
+      def upload(key:, body:, content_type: nil, cache_control: nil)
+        opts = { bucket: bucket, key: key, body: body }
+        opts[:content_type] = content_type if content_type
+        opts[:cache_control] = cache_control if cache_control
+        client.put_object(**opts)
+        url(key: key)
+      end
+
+      def download(key:)
+        client.get_object(bucket: bucket, key: key).body.read
+      end
+
+      def url(key:)
+        "https://#{bucket}.s3.#{region}.amazonaws.com/#{key}"
+      end
+
+      def signed_url(key:, expires_in: 3600)
+        require "aws-sdk-s3"
+        Aws::S3::Presigner.new(client: client).presigned_url(:get_object, bucket: bucket, key: key, expires_in: expires_in)
+      end
+
+      def exists?(key:)
+        client.head_object(bucket: bucket, key: key)
+        true
+      rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::NoSuchKey
+        false
+      end
+
+      def delete(key:)
+        client.delete_object(bucket: bucket, key: key)
+      end
+
+      def list(prefix: nil, max: 1000)
+        resp = client.list_objects_v2(bucket: bucket, prefix: prefix, max_keys: max)
+        resp.contents.map(&:key)
+      end
+
+      def bucket
+        prefix = Studio.s3_bucket_prefix
+        raise NotConfigured, "Studio.s3_bucket_prefix not set in config/initializers/studio.rb" if prefix.nil? || prefix.empty?
+        "#{prefix}-#{environment}"
+      end
+
+      def region
+        Studio.s3_region
+      end
+
+      def client
+        @client ||= begin
+          require "aws-sdk-s3"
+          Aws::S3::Client.new(region: region)
+        end
+      end
+
+      def reset!
+        @client = nil
+      end
+
+      private
+
+      def environment
+        defined?(Rails) && Rails.env.production? ? "production" : "dev"
+      end
+    end
+  end
+end

data/lib/studio/theme_resolver.rb

@@ -0,0 +1,99 @@
+module Studio
+  class ThemeResolver
+    ROLES = %i[primary dark light success warning danger accent].freeze
+
+    attr_reader :colors
+
+    # colors: hash of role => hex string (e.g. { primary: "#8E82FE", dark: "#1A1535", ... })
+    def initialize(colors = {})
+      @colors = colors.symbolize_keys
+    end
+
+    def to_css
+      dark_vars  = dark_mode_vars.map { |k, v| "  #{k}: #{v};" }.join("\n")
+      light_vars = light_mode_vars.map { |k, v| "  #{k}: #{v};" }.join("\n")
+      palette_vars = primary_palette_vars.map { |k, v| "  #{k}: #{v};" }.join("\n")
+
+      <<~CSS
+        :root, .dark {
+        #{dark_vars}
+        #{palette_vars}
+        }
+
+        html:not(.dark) {
+        #{light_vars}
+        #{palette_vars}
+        }
+      CSS
+    end
+
+    def dark_mode_vars
+      dark_base   = colors[:dark] || "#1A1535"
+      primary     = colors[:primary] || "#8E82FE"
+      border_rgb  = ColorScale.lighten(dark_base, 0.30)
+
+      {
+        "--color-page"           => dark_base,
+        "--color-surface"        => ColorScale.lighten(dark_base, 0.15),
+        "--color-surface-alt"    => ColorScale.darken(dark_base, 0.14),
+        "--color-inset"          => ColorScale.darken(dark_base, 0.43),
+        "--color-text"           => "#ffffff",
+        "--color-text-body"      => "#e2e8f0",
+        "--color-text-secondary" => "#94a3b8",
+        "--color-text-muted"     => "#64748b",
+        "--color-border"         => ColorScale.with_opacity(border_rgb, 0.2),
+        "--color-border-strong"  => ColorScale.with_opacity(border_rgb, 0.4),
+        "--color-shadow"         => "transparent",
+        "--color-cta"            => primary,
+        "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
+        "--color-success"        => colors[:success] || "#4BAF50",
+        "--color-warning"        => colors[:warning] || "#FF7C47",
+        "--color-danger"         => colors[:danger] || "#EF4444"
+      }
+    end
+
+    # Generate --color-primary-{50..900} + RGB variants for Tailwind opacity support
+    def primary_palette_vars
+      primary = colors[:primary] || "#8E82FE"
+      scale = ColorScale.generate(primary)
+      vars = {}
+
+      scale.each do |shade, hex|
+        vars["--color-primary-#{shade}"] = hex
+        r, g, b = ColorScale.hex_to_rgb(hex)
+        vars["--color-primary-#{shade}-rgb"] = "#{r} #{g} #{b}"
+      end
+
+      # DEFAULT aliases
+      r, g, b = ColorScale.hex_to_rgb(primary)
+      vars["--color-primary"] = primary
+      vars["--color-primary-rgb"] = "#{r} #{g} #{b}"
+
+      vars
+    end
+
+    def light_mode_vars
+      light_base = colors[:light] || "#f8fafc"
+      primary    = colors[:primary] || "#8E82FE"
+
+      {
+        "--color-page"           => light_base,
+        "--color-surface"        => "#ffffff",
+        "--color-surface-alt"    => ColorScale.darken(light_base, 0.03),
+        "--color-inset"          => ColorScale.darken(light_base, 0.08),
+        "--color-text"           => "#0f172a",
+        "--color-text-body"      => "#334155",
+        "--color-text-secondary" => "#64748b",
+        "--color-text-muted"     => "#94a3b8",
+        "--color-border"         => ColorScale.darken(light_base, 0.08),
+        "--color-border-strong"  => ColorScale.darken(light_base, 0.15),
+        "--color-shadow"         => "rgba(0,0,0,0.05)",
+        "--color-cta"            => primary,
+        "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
+        "--color-success"        => colors[:success] || "#4BAF50",
+        "--color-warning"        => colors[:warning] || "#FF7C47",
+        "--color-danger"         => colors[:danger] || "#EF4444"
+      }
+    end
+  end
+end

data/lib/studio/username_generator.rb

@@ -0,0 +1,21 @@
+module Studio
+  class UsernameGenerator
+    def self.generate
+      2.times do
+        candidate = build_name
+        return candidate unless User.exists?(username: candidate)
+      end
+      "#{build_name}-#{rand(1000..9999)}"
+    end
+
+    def self.build_name
+      plant = Faker::Food.send(%i[vegetables fruits].sample)
+      animal = Faker::Creature::Animal.name
+      "#{sanitize(plant)}-#{sanitize(animal)}"
+    end
+
+    def self.sanitize(str)
+      str.downcase.gsub(/[^a-z0-9]/, "-").gsub(/-+/, "-").gsub(/^-|-$/, "")
+    end
+  end
+end

data/lib/studio/version.rb

@@ -0,0 +1,3 @@
+module Studio
+  VERSION = "0.4.1"
+end

data/lib/studio-engine.rb

@@ -0,0 +1,5 @@
+# Entry point for the `studio-engine` gem. The actual code lives in
+# `lib/studio.rb` (which exports the `Studio` module). This shim exists so
+# `gem "studio-engine"` in a Gemfile loads correctly without consumers
+# needing to add `require: "studio"`.
+require_relative "studio"

data/lib/studio.rb

@@ -0,0 +1,134 @@
+require "studio/version"
+require "studio/engine"
+require "studio/color_scale"
+require "studio/theme_resolver"
+require "studio/username_generator"
+require "studio/s3"
+require "studio/image_cache"
+
+module Studio
+  mattr_accessor :app_name,            default: "Studio"
+  mattr_accessor :session_key,         default: :user_id
+  mattr_accessor :welcome_message,     default: ->(user) { "Welcome, #{user.display_name}!" }
+  mattr_accessor :registration_params, default: [:name, :email, :password, :password_confirmation]
+  mattr_accessor :configure_new_user,  default: ->(user) {}
+  mattr_accessor :configure_sso_user,  default: ->(user) {}
+  mattr_accessor :sso_logo,            default: nil
+  mattr_accessor :theme_logos,         default: []
+
+  # Theme role colors (7 roles)
+  mattr_accessor :theme_primary,  default: "#8E82FE"
+  mattr_accessor :theme_dark,     default: "#1A1535"
+  mattr_accessor :theme_light,    default: "#f8fafc"
+  mattr_accessor :theme_success,  default: "#4BAF50"
+  mattr_accessor :theme_warning,  default: "#FF7C47"
+  mattr_accessor :theme_danger,   default: "#EF4444"
+  mattr_accessor :theme_accent,   default: "#F72585"
+
+  # S3 / object storage — host apps MUST set s3_bucket_prefix explicitly in
+  # config/initializers/studio.rb before any S3-touching code runs (ImageCache,
+  # Studio::S3.upload, etc.). Default is nil so external users don't accidentally
+  # target someone else's bucket if they forget to configure.
+  #
+  # Bucket name resolves to "#{s3_bucket_prefix}-#{Rails.env.production? ? 'production' : 'dev'}".
+  mattr_accessor :s3_bucket_prefix, default: nil
+  mattr_accessor :s3_region,        default: "us-east-2"
+
+  class S3ConfigError < StandardError; end
+
+  # Whether to validate the host app's User model at boot. See docs/USER_CONTRACT.md.
+  # Set to false in config/initializers/studio.rb to bypass (e.g. during migrations
+  # that intentionally break the contract).
+  mattr_accessor :validate_user_contract, default: true
+
+  # Only methods that consumers must explicitly define are checked here.
+  # Column accessors (#email, #name, #role) are NOT validated because
+  # 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_CLASS_METHODS    = %i[find_by].freeze
+
+  class UserContractError < StandardError; end
+
+  def self.configure
+    yield self
+  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
+  # Engine#after_initialize. Opt out via Studio.validate_user_contract = false.
+  def self.validate_user_contract!(user_class)
+    return unless validate_user_contract
+    return unless user_class.is_a?(Class)
+
+    missing = []
+    REQUIRED_USER_CLASS_METHODS.each do |m|
+      missing << "User.#{m}" unless user_class.respond_to?(m)
+    end
+    REQUIRED_USER_INSTANCE_METHODS.each do |m|
+      missing << "User##{m}" unless user_class.instance_methods.include?(m)
+    end
+
+    return if missing.empty?
+
+    raise UserContractError, <<~MSG
+      The studio-engine gem's expected User model contract is not satisfied.
+
+      Missing: #{missing.join(", ")}
+
+      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
+
+      To bypass this check temporarily, set Studio.validate_user_contract = false
+      in config/initializers/studio.rb.
+    MSG
+  end
+
+  def self.theme_config
+    {
+      primary: theme_primary,
+      dark:    theme_dark,
+      light:   theme_light,
+      success: theme_success,
+      warning: theme_warning,
+      danger:  theme_danger,
+      accent:  theme_accent
+    }.compact
+  end
+
+  # Find a logo from theme_logos by title, with fallback chain:
+  # 1. Exact title match
+  # 2. "Navbar Logo" fallback
+  # 3. First logo in the list
+  def self.logo_for(title)
+    logos = theme_logos.map { |l| l.is_a?(Hash) ? l : { file: l, title: l } }
+    entry = logos.find { |l| l[:title] == title }
+    entry ||= logos.find { |l| l[:title] == "Navbar Logo" }
+    entry ||= logos.first
+    entry ? "/#{entry[:file]}" : nil
+  end
+
+  def self.routes(router)
+    router.instance_exec do
+      get  "login",  to: "sessions#new"
+      post "login",  to: "sessions#create"
+      post "sso_continue", to: "sessions#sso_continue"
+      get  "sso_login",    to: "sessions#sso_login"
+      get  "logout", to: "sessions#destroy"
+      get  "signup", to: "registrations#new"
+      post "signup", to: "registrations#create"
+      get  "auth/:provider/callback", to: "omniauth_callbacks#create"
+      get  "auth/failure", to: "omniauth_callbacks#failure"
+      resources :error_logs, only: [:index, :show]
+
+      # Admin
+      get   "admin/theme",            to: "theme_settings#edit",       as: :admin_theme
+      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
+    end
+  end
+end

data/studio-engine.gemspec

@@ -0,0 +1,30 @@
+require_relative "lib/studio/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "studio-engine"
+  spec.version     = Studio::VERSION
+  spec.authors     = ["Alex McRitchie"]
+  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.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",
+    "bug_tracker_uri" => "https://github.com/amcritchie/studio-engine/issues",
+    "changelog_uri"   => "https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md"
+  }
+
+  spec.files = Dir["lib/**/*", "app/**/*", "config/**/*", "tailwind/**/*", "Gemfile", "studio-engine.gemspec", "README.md", "CHANGELOG.md", "LICENSE"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 7.0"
+  spec.add_dependency "tailwindcss-rails", "~> 2.7"
+  spec.add_dependency "faker", ">= 2.0"
+  spec.add_dependency "solid_queue"
+  spec.add_dependency "aws-sdk-s3", "~> 1.218"
+  spec.add_dependency "mini_magick", "~> 5.0"
+end

data/tailwind/studio.tailwind.config.js

@@ -0,0 +1,94 @@
+// Shared Tailwind config for all Studio apps
+// Apps spread from this in their own tailwind.config.js
+
+module.exports = {
+  darkMode: 'class',
+  theme: {
+    fontFamily: {
+      sans: ['Montserrat', 'system-ui', 'sans-serif'],
+      mono: ['ui-monospace', 'SFMono-Regular', 'monospace'],
+    },
+    extend: {
+      colors: {
+        // Theme-aware semantic tokens (reference CSS variables)
+        page:          'var(--color-page)',
+        surface:       'var(--color-surface)',
+        'surface-alt': 'var(--color-surface-alt)',
+        inset:         'var(--color-inset)',
+
+        // Dynamic primary palette (from theme role colors)
+        primary: {
+          DEFAULT: 'rgb(var(--color-primary-rgb) / <alpha-value>)',
+          50:  'rgb(var(--color-primary-50-rgb) / <alpha-value>)',
+          100: 'rgb(var(--color-primary-100-rgb) / <alpha-value>)',
+          200: 'rgb(var(--color-primary-200-rgb) / <alpha-value>)',
+          300: 'rgb(var(--color-primary-300-rgb) / <alpha-value>)',
+          400: 'rgb(var(--color-primary-400-rgb) / <alpha-value>)',
+          500: 'rgb(var(--color-primary-500-rgb) / <alpha-value>)',
+          600: 'rgb(var(--color-primary-600-rgb) / <alpha-value>)',
+          700: 'rgb(var(--color-primary-700-rgb) / <alpha-value>)',
+          800: 'rgb(var(--color-primary-800-rgb) / <alpha-value>)',
+          900: 'rgb(var(--color-primary-900-rgb) / <alpha-value>)',
+        },
+
+        mint: {
+          DEFAULT: '#06D6A0',
+          50: '#e6faf4',
+          100: '#b3f0de',
+          200: '#80e6c8',
+          300: '#4ddcb2',
+          400: '#1ad29c',
+          500: '#06D6A0',
+          600: '#05b888',
+          700: '#049a70',
+          800: '#037c58',
+          900: '#025e40',
+        },
+        navy: {
+          DEFAULT: '#1A1535',
+          50: '#e8e7ed',
+          100: '#b8b5c8',
+          200: '#8883a3',
+          300: '#58517e',
+          400: '#3a3359',
+          500: '#1A1535',
+          600: '#16122e',
+          700: '#120f27',
+          800: '#0e0c20',
+          900: '#0a0919',
+        },
+        violet: {
+          DEFAULT: '#8E82FE',
+          50: '#f0eeff',
+          100: '#EAE8FF',
+          200: '#b2aafe',
+          300: '#C5C0FE',
+          400: '#8E82FE',
+          500: '#8E82FE',
+          600: '#6558e5',
+          700: '#6558E0',
+          800: '#3b2cb3',
+          900: '#3D2FB5',
+        },
+        mist: '#F7F6FF',
+        lavender: '#E8E6F0',
+        slate: '#6B6580',
+        charcoal: '#2D2648',
+        midnight: '#120F28',
+        ember: '#FF8C69',
+        gold: '#FFD166',
+        magenta: '#F72585',
+      },
+      textColor: {
+        heading:   'var(--color-text)',
+        body:      'var(--color-text-body)',
+        secondary: 'var(--color-text-secondary)',
+        muted:     'var(--color-text-muted)',
+      },
+      borderColor: {
+        subtle: 'var(--color-border)',
+        strong: 'var(--color-border-strong)',
+      },
+    },
+  },
+}