Improve webhook verification.

[tristandunn]

While implementing verification for a webhook endpoint I was attempt to follow the instructions included the API documentation:

An Authorization header is included with every fired webhook so you can be sure the request came from RubyGems.org. The value of the header is the SHA2-hashed concatenation of the gem name, the gem version and your API key.

The issue here is "your API key" is unclear and not what I expected at all.

I created a scoped API key with webhook access and used it to create a webhook. However when testing the verification for the webhook I could not successfully compute a signature that matched what was sent in the Authorization header.

After a lot of debugging, wasted time, and even talking to Claude Code I eventually noticed that since #3151 was merged in July 2022 webhook verification favors the user API key before falling back to the first hashed API key for the user. Which it still does today:

rubygems.org/app/models/web_hook.rb

Lines 33 to 35 in c3cda23

	def api_key
	user.api_key || user.api_keys.first&.hashed_key
	end

Great, problem solved, right? Not quite, since I could not find where my user API key is actually available for me to see. After searching I found it in two places, a feed on the dashboard and the feeds layout. That's not really an ideal user experience.

To add to all this, it's not entirely clear to me if the user API key is still meant to be around or not since the introduction of the scoped API keys. I started to think my account being so old I simply needed to have support clear my user API key out, but that doesn't really hold up if it's still being used for private feeds.

Is your feature request related to a problem?

Yes, it's unclear what key to use for webhook verification or even where to find it. This led to a lot of confusion and even more wasted time to determine how to correctly verify a webhook. My best guess is if anyone has tried to implement this recently they've likely skipped out on the verification.

Describe the solution you'd like

Ideally the API key used to create the webhook would be the key that's used to verify it, which means the webhook would need an API key association. It could fallback to the existing method for webhooks that weren't created with a specific key.

Describe alternatives you've considered

1. Display the user key in the API key list, describing it as the generic API key for private feed retrieval and webhook verification. This is the quickest solution and not technically a security issue if it's already clearly available in the HTML.
2. Since there is the ability to reset a user API key when resetting your password, it'd be nice to display it there so we can at least get access to it and allow manual rotations when needed.

Additional context

Regardless of the solution, the documentation should be updated to clarify what "your API key" means in the context of webhook verification and where to find the key.

[simi]

Thanks for the report. Webhooks deserve new guide to explain properly, I agree. https://guides.rubygems.org/rubygems-org-api/#webhook-methods this is the only docs around in current Guides. If I remember well user.api_key is something related only to users registered before multi-keys were added.

Ideally the API key used to create the webhook would be the key that's used to verify it, which means the webhook would need an API key association. It could fallback to the existing method for webhooks that weren't created with a specific key.

Alternatively to your suggestion, do you think it will make sense to make api key selected during webhook creation? That way user can specify which key is related to the given hook. Or at least to make it option and fall back to the API key used during creation? 🤔

[tristandunn]

Alternatively to your suggestion, do you think it will make sense to make api key selected during webhook creation?

How would the user select which API key to use, separately provide the token for the API key to use? I was going to suggest name, but it doesn't look like that's a unique value.

I think to start I'd favor using the key used to create the webhook, and perhaps consider following it up with the ability to select an API key if desired. That keeps the existing API behavior and, in my opinion, makes it act as I'd expect.

If an API key association was added the webhooks, the user.api_keys.first could be backfilled into the association and the method could be updated to:

def api_key 
  super || user.api_key
end 

That should allow existing webhooks to continue to work as they do today, but going forward the association would be assigned the API key used to create the webhook instead.