Restrict server-side URL validation to allowlisted hosts (SSRF protection)

Server-side HEAD requests for URL validation could be exploited for SSRF
attacks against internal networks. This change restricts validation to a
trusted allowlist of avatar hosts:

- gravatar.com, www.gravatar.com, secure.gravatar.com
- avatars.githubusercontent.com

Non-allowlisted URLs skip server-side validation entirely and rely on
client-side error handling via the avatar-fallback web component. This
provides defense in depth:

- Allowlisted hosts: Server-side validation (no flicker for broken URLs)
- Other hosts: Client-side fallback (may flicker briefly on 404)

Author: akabiru

app/components/primer/open_project/avatar_with_fallback.rb

@@ -22,6 +22,15 @@ class AvatarWithFallback < Primer::Beta::Avatar
       # Set to false to disable server-side URL validation (useful for tests)
       mattr_accessor :validate_urls, default: true
 
+      # Allowlist of trusted avatar hosts for server-side validation.
+      # Only these hosts will be checked via HEAD request to avoid SSRF vulnerabilities.
+      ALLOWED_AVATAR_HOSTS = %w[
+        gravatar.com
+        www.gravatar.com
+        secure.gravatar.com
+        avatars.githubusercontent.com
+      ].freeze
+
       # @see
       #   - https://primer.style/foundations/typography/
       #   - https://github.com/primer/css/blob/main/src/support/variables/typography.scss
@@ -68,15 +77,18 @@ def require_src_or_alt_arguments(src, alt)
       def resolve_src(src)
         return @fallback_svg if src.blank?
 
-        if validate_urls
-          return @fallback_svg if absolute_url?(src) && !url_accessible?(src)
+        if validate_urls && allowed_host?(src) && !url_accessible?(src)
+          return @fallback_svg
         end
 
         src
       end
 
-      def absolute_url?(url)
-        url.to_s.match?(%r{\Ahttps?://}i)
+      def allowed_host?(url)
+        uri = URI.parse(url)
+        ALLOWED_AVATAR_HOSTS.include?(uri.host&.downcase)
+      rescue URI::InvalidURIError
+        false
       end
 
       def url_accessible?(url)

previews/primer/open_project/avatar_with_fallback_preview.rb

@@ -69,37 +69,49 @@ def fallback_as_link
 
       # @!group Error Handling (404 Fallback)
       #
-      # @label Broken absolute URL (server-side fallback)
+      # @label Broken Gravatar (server-side, no flicker)
       # @snapshot
-      def broken_absolute_url
-        # Absolute URLs are validated server-side via HEAD request
+      def broken_gravatar_url
+        # Gravatar URLs are in the allowlist - validated server-side via HEAD request
         # If inaccessible, fallback SVG is rendered immediately (no flicker)
         render(Primer::OpenProject::AvatarWithFallback.new(
-          src: "https://example.com/non-existent-avatar.png",
-          alt: "User With Missing Avatar",
+          src: "https://gravatar.com/avatar/nonexistent123",
+          alt: "User With Missing Gravatar",
           unique_id: 42
         ))
       end
 
-      # @label Multiple broken absolute URLs (server-side)
-      def multiple_broken_absolute_urls
+      # @label Multiple broken Gravatars (server-side)
+      def multiple_broken_gravatar_urls
         render_with_template(locals: {})
       end
 
+      # @label Broken non-allowlisted URL (client-side fallback)
+      # @snapshot
+      def broken_non_allowlisted_url
+        # Non-allowlisted hosts skip server-side validation (SSRF protection)
+        # Client-side JS handles the error and swaps to fallback SVG (may flicker)
+        render(Primer::OpenProject::AvatarWithFallback.new(
+          src: "https://example.com/non-existent-avatar.png",
+          alt: "User With Missing Avatar",
+          unique_id: 43
+        ))
+      end
+
       # @label Broken relative URL (client-side fallback)
       # @snapshot
       def broken_relative_url
         # Relative URLs cannot be validated server-side (no host context)
-        # Client-side JS handles the error and swaps to fallback SVG
+        # Client-side JS handles the error and swaps to fallback SVG (may flicker)
         render(Primer::OpenProject::AvatarWithFallback.new(
           src: "/non-existent-avatar.png",
           alt: "User With Missing Avatar",
-          unique_id: 43
+          unique_id: 44
         ))
       end
 
-      # @label Multiple broken relative URLs (client-side)
-      def multiple_broken_relative_urls
+      # @label Multiple broken non-allowlisted URLs (client-side)
+      def multiple_broken_non_allowlisted_urls
         render_with_template(locals: {})
       end
       #

previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_gravatar_urls.html.erb

@@ -0,0 +1,8 @@
+<div class="d-flex gap-3 flex-items-center">
+  <p class="color-fg-muted">Gravatar URLs are validated server-side. Broken URLs render fallback immediately (no flicker):</p>
+</div>
+<div class="d-flex gap-3 flex-items-center mt-2">
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://gravatar.com/avatar/nonexistent-alice", alt: "Alice Johnson", unique_id: 10)) %>
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://gravatar.com/avatar/nonexistent-bob", alt: "Bob Smith", unique_id: 20)) %>
+  <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://secure.gravatar.com/avatar/nonexistent-charlie", alt: "Charlie Brown", unique_id: 30)) %>
+</div>

…w/multiple_broken_absolute_urls.html.erb …ple_broken_non_allowlisted_urls.html.erbpreviews/primer/open_project/avatar_with_fallback_preview/multiple_broken_absolute_urls.html.erb renamed to previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_non_allowlisted_urls.html.erb previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_absolute_urls.html.erb renamed to previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_non_allowlisted_urls.html.erb

@@ -1,5 +1,5 @@
 <div class="d-flex gap-3 flex-items-center">
-  <p class="color-fg-muted">Absolute URLs are validated server-side. Broken URLs render fallback immediately (no flicker):</p>
+  <p class="color-fg-muted">Non-allowlisted URLs skip server-side validation (SSRF protection). Client-side JS handles errors (may flicker):</p>
 </div>
 <div class="d-flex gap-3 flex-items-center mt-2">
   <%= render(Primer::OpenProject::AvatarWithFallback.new(src: "https://example.com/missing/alice.png", alt: "Alice Johnson", unique_id: 10)) %>

previews/primer/open_project/avatar_with_fallback_preview/multiple_broken_relative_urls.html.erb

@@ -5,15 +5,6 @@
 class PrimerOpenProjectAvatarStackTest < Minitest::Test
   include Primer::ComponentTestHelpers
 
-  def setup
-    @original_validate_urls = Primer::OpenProject::AvatarWithFallback.validate_urls
-    Primer::OpenProject::AvatarWithFallback.validate_urls = false
-  end
-
-  def teardown
-    Primer::OpenProject::AvatarWithFallback.validate_urls = @original_validate_urls
-  end
-
   def test_renders_with_image_avatars
     render_inline(Primer::OpenProject::AvatarStack.new) do |component|
       component.with_avatar_with_fallback(src: "https://github.com/github.png", alt: "@github")

test/components/open_project/avatar_stack_test.rb

@@ -1,20 +1,11 @@
 # frozen_string_literal: true
 
 require "components/test_helper"
+require "webmock/minitest"
 
 class PrimerOpenProjectAvatarWithFallbackTest < Minitest::Test
   include Primer::ComponentTestHelpers
 
-  def setup
-    # Disable URL validation by default in tests to avoid HTTP requests
-    @original_validate_urls = Primer::OpenProject::AvatarWithFallback.validate_urls
-    Primer::OpenProject::AvatarWithFallback.validate_urls = false
-  end
-
-  def teardown
-    Primer::OpenProject::AvatarWithFallback.validate_urls = @original_validate_urls
-  end
-
   def test_renders_image_avatar_with_src
     render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://github.com/github.png", alt: "github"))
 
@@ -41,14 +32,63 @@ def test_image_avatar_error_handling_setup
     assert_includes svg_content, ">AJ<", "Fallback SVG should contain initials 'AJ'"
   end
 
-  def test_falls_back_when_absolute_url_is_inaccessible
+  def test_skips_validation_for_non_allowlisted_hosts
+    Primer::OpenProject::AvatarWithFallback.validate_urls = true
+    # url_accessible? should NOT be called for non-allowlisted hosts
+    Primer::OpenProject::AvatarWithFallback.any_instance.expects(:url_accessible?).never
+
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://example.com/avatar.png", alt: "Test User", unique_id: 43))
+
+    # Should render the original URL (no server-side validation for non-allowlisted hosts)
+    assert_selector("avatar-fallback") do
+      assert_selector("img.avatar[src='https://example.com/avatar.png']")
+    end
+  end
+
+  def test_handles_invalid_uri_in_allowed_host_check
     Primer::OpenProject::AvatarWithFallback.validate_urls = true
-    Primer::OpenProject::AvatarWithFallback.any_instance.stubs(:url_accessible?).returns(false)
 
-    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://broken.example.com/avatar.png", alt: "Test User", unique_id: 42))
+    # Invalid URI should not raise, just skip validation
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "not a valid uri %%", alt: "Test User", unique_id: 45))
 
-    # Should render fallback SVG when URL is inaccessible
-    assert_selector("avatar-fallback[data-unique-id='42']") do
+    # Should render the original URL (invalid URI treated as non-allowlisted)
+    assert_selector("avatar-fallback") do
+      assert_selector("img.avatar[src='not a valid uri %%']")
+    end
+  end
+
+  def test_url_accessible_returns_true_for_successful_head_request
+    Primer::OpenProject::AvatarWithFallback.validate_urls = true
+    stub_request(:head, "https://gravatar.com/avatar/exists").to_return(status: 200)
+
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://gravatar.com/avatar/exists", alt: "Test User", unique_id: 46))
+
+    # Should render original URL when HEAD request succeeds
+    assert_selector("avatar-fallback") do
+      assert_selector("img.avatar[src='https://gravatar.com/avatar/exists']")
+    end
+  end
+
+  def test_url_accessible_returns_false_for_404_response
+    Primer::OpenProject::AvatarWithFallback.validate_urls = true
+    stub_request(:head, "https://gravatar.com/avatar/notfound").to_return(status: 404)
+
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://gravatar.com/avatar/notfound", alt: "Test User", unique_id: 47))
+
+    # Should render fallback SVG when HEAD request returns 404
+    assert_selector("avatar-fallback") do
+      assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
+    end
+  end
+
+  def test_url_accessible_returns_false_on_network_error
+    Primer::OpenProject::AvatarWithFallback.validate_urls = true
+    stub_request(:head, "https://gravatar.com/avatar/timeout").to_timeout
+
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://gravatar.com/avatar/timeout", alt: "Test User", unique_id: 48))
+
+    # Should render fallback SVG when network error occurs
+    assert_selector("avatar-fallback") do
       assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
     end
   end
@@ -76,12 +116,6 @@ def test_defaults_to_size_20
     assert_selector("img.avatar[size=20][height=20][width=20]")
   end
 
-  def test_fallback_defaults_to_size_20
-    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: nil, alt: "Test User"))
-
-    assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
-  end
-
   def test_falls_back_when_size_isn_t_valid
     without_fetch_or_fallback_raises do
       render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://github.com/github.png", alt: "github", size: 1_000_000_000))
@@ -171,15 +205,6 @@ def test_fallback_with_unique_id_in_data_attribute
     end
   end
 
-  def test_fallback_without_unique_id
-    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: nil, alt: "Test User"))
-
-    # Should still render, just without unique_id data attribute
-    assert_selector("avatar-fallback[data-alt-text='Test User']") do
-      assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
-    end
-  end
-
   def test_adds_custom_classes
     render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://github.com/github.png", alt: "github", classes: "custom-class"))
 
@@ -208,12 +233,14 @@ def test_raises_when_both_src_and_alt_are_blank
     assert_includes(error.message, "`src` or `alt` is required")
   end
 
-  def test_fallback_with_single_word_name
+  def test_fallback_extracts_single_initial_from_single_word_name
     render_inline(Primer::OpenProject::AvatarWithFallback.new(src: nil, alt: "Alice"))
 
-    assert_selector("avatar-fallback") do
-      assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
-    end
+    fallback_wrapper = page.find("avatar-fallback")
+    fallback_src = fallback_wrapper["data-fallback-src"]
+    svg_content = Base64.decode64(fallback_src.sub("data:image/svg+xml;base64,", ""))
+
+    assert_includes svg_content, ">A<", "Single word name should produce single initial 'A'"
   end
 
   def test_status

test/components/open_project/avatar_with_fallback_test.rb

@@ -32,5 +32,8 @@
 
 require File.expand_path("../demo/config/environment.rb", __dir__)
 
+# Disable server-side URL validation in tests to avoid HTTP requests
+Primer::OpenProject::AvatarWithFallback.validate_urls = false
+
 # used by SelectPanel
 Mime::Type.register "text/fragment+html", :html_fragment