Websubhub subscription auto-verification proposal discussion

[ayeshLK]

Please use this issue to discuss the Auto-verify subscriptions in Ballerina WebSubHub

[daneshk]

One Question,

What if we have autoVerifySubscription disabled at the service level and we mark it as verified at the onSubscription method?
What if we have autoVerifySubscription enabled at the service level and we don't mark it as verified at the onSubscription method?

Shall we cover these in the proposal.

[ayeshLK]

One Question,

What if we have autoVerifySubscription disabled at the service level and we mark it as verified at the onSubscription method? What if we have autoVerifySubscription enabled at the service level and we don't mark it as verified at the onSubscription method?

Shall we cover these in the proposal.

The behavior would be like this [1]:

• If autoVerifySubscription is enabled in websubhub:ServiceConfig and the developer marks the subscription as auto-verifiable, the hub skips the subscription intent verification step.
• If autoVerifySubscription is disabled and the developer marks the subscription as auto-verifiable, the websubhub:Controller will throw and error saying marking subscription as auto-verifiable but the configuration has not been turned-on.
• If autoVerifySubscription is enabled and the subscription is not explicitly marked as auto-verifiable, the hub follows the standard challenge-response verification process.
• If autoVerifySubscription is disabled and the subscription is not explicitly marked as auto-verifiable, the hub follows the standard challenge-response verification process.

I have also updated the proposal.

[1] - https://github.com/ballerina-platform/ballerina-spec/blob/d877e7412baf975acd3799d24f21cdf84583a58d/stdlib/proposals/websubhub/subscription_autoverification.md#behavior

[MaryamZi]

1. The proposal seems to be using "subscription verification" and "intent verification" interchangeably. Isn't subscription verification too broad a term for "intent verification"? Shall we stick to "intent verification"? Especially, since subscription validation is a separate thing.

2. Quoting the WebSub spec, intent verification is

   In order to prevent an attacker from creating unwanted subscriptions on behalf of a subscriber (or unsubscribing desired ones), a hub must ensure that the subscriber did indeed send the subscription request.

   The proposal says

   enables the developer to disable the WebSub subscription verification process for well known or authenticated subscriptions

   Given the purpose of intent verification, is the usage of "well-known/authenticated" ideal here? Maybe we could consider saying "authorized" clients, but even then, don't we need more of an explanation as to how they become an alternative for intent verification?

3. Assuming by throw you meant a panic, is it correct to panic, given how we try to avoid panics?

   If autoVerifySubscription is disabled and the developer marks the subscription as auto-verifiable, the websubhub:Controller will throw and error saying marking subscription as auto-verifiable but the configuration has not been turned-on.

4. As you've mentioned, "This feature might be a potential violation of the defined WebSub standard". Given this and other verification methods like the ping approach, have we considered extending the WebSub hub and providing like a webhook provider module that allows more flexibility (without changing the WebSub hub module, which can continue to be fully spec-compliant)?

[ayeshLK]

@MaryamZi please find my inline comments.

1. The proposal seems to be using "subscription verification" and "intent verification" interchangeably. Isn't subscription verification too broad a term for "intent verification"? Shall we stick to "intent verification"? Especially, since subscription validation is a separate thing.

+1

2. Quoting the WebSub spec, intent verification is

   In order to prevent an attacker from creating unwanted subscriptions on behalf of a subscriber (or unsubscribing desired ones), a hub must ensure that the subscriber did indeed send the subscription request.

The proposal says

enables the developer to disable the WebSub subscription verification process for well known or authenticated subscriptions

Given the purpose of intent verification, is the usage of "well-known/authenticated" ideal here? Maybe we could consider saying "authorized" clients, but even then, don't we need more of an explanation as to how they become an alternative for intent verification?

Yes, as you mentioned, intent verification is designed to prevent malicious third parties from subscribing or unsubscribing a subscriber from the hub without authorization.

However, in practical implementations, subscribers (80% of the cases) are already authenticated and authorized via other security mechanisms (OAuth2 with scopes, API keys etc). In such cases the subscription intent verification will be an additional layer rather than a necessary one. This proposal aims to provide the flexibility for implementers to opt-out of (or override) the subscription intent verification flow in a WebSub hub when robust authentication and authorization mechanisms are already in place.

Regarding terminology, we can refine well-known or authenticated to authenticated and authorized clients for greater clarity.

3. Assuming by throw you meant a panic, is it correct to panic, given how we try to avoid panics?
   If autoVerifySubscription is disabled and the developer marks the subscription as auto-verifiable, the websubhub:Controller will throw and error saying marking subscription as auto-verifiable but the configuration has not been turned-on.

Here throwing an error does not mean panic. If you refer the websubhub:Controller API, you could see that the markAsVerified API returns websubhub:Error or nil. And furthermore in the reference implementation we can see that the websubhub:Controller usage within the onSubscription and onUnsubscription methods and if there is an error it will send an error response to the subscriber rather than crashing the service.

To avoid any ambiguity, I will refine the wording in the Behavior section to provide more clarity on this aspect.

4. As you've mentioned, "This feature might be a potential violation of the defined WebSub standard". Given this and other verification methods like the ping approach, have we considered extending the WebSub hub and providing like a webhook provider module that allows more flexibility (without changing the WebSub hub module, which can continue to be fully spec-compliant)?

This feature does not violate the WebSub standard; rather, it serves as an extension that allows implementers to opt out of subscription intent verification based on their specific requirements. The key distinction here is that while an implementation might deviate from the standard, the library itself remains compliant.

But, as per the practical usage of the library, the implementer should have the freedom to expand and define there own protocol on how they want to verify subscriptions. A notable example is GitHub webhooks, which function as a WebSub hub but employ a subscription intent verification mechanism that differs from the WebSub standard.

And introducing a separate module to deal with this particular usecase will be redundant effort as the only difference (or feature) we want to bring in here is how an implementer can skip subscription intent verification. And the ping payload based approach is again not websub standard compliant hence the implementation would not be fully websub compliant IMO.