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

@@ -41,18 +41,32 @@ 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_falls_back_when_allowed_host_url_is_inaccessible
     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))
+    # Uses gravatar.com which is in the allowlist
+    render_inline(Primer::OpenProject::AvatarWithFallback.new(src: "https://gravatar.com/avatar/nonexistent", alt: "Test User", unique_id: 42))
 
     # Should render fallback SVG when URL is inaccessible
     assert_selector("avatar-fallback[data-unique-id='42']") do
       assert_selector("img.avatar[src^='data:image/svg+xml;base64,']")
     end
   end
 
+  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_renders_fallback_when_src_is_nil
     render_inline(Primer::OpenProject::AvatarWithFallback.new(src: nil, alt: "OpenProject Admin"))