Introduction

The Fedi Links Project promotes web+* links as a way to support protocols over platforms. However, simply using web+* links would lead to a greatly worsened user experience. This specification aims to improve one of the factors relevant to user experience for web+* links.

The desired behavior

If someone clicks a web+* link, for example a web+ap link, then it should open in their protocol client, for example a Mastodon client. Unfortunately, this only works if they already have a client installed for a given protocol, but we don’t actually want to require them to. Instead, if they don’t have a client installed, it should be possible to use the browser to provide at least some sort of view of the link.

In other words, we want it such that someone with a client will just use the client to view web+* links, while someone without a client will use the browser. Obviously this will require some sort of API to allow the host to translate web+* links into something that can be viewed in the browser.

The Well-Known Protocol Handler and when to use it

The Well-Known Protocol Handler, described here, is just such API. Located at /.well-known/protocol-handler it SHALL accept a query param target containing the appropriately-encoded URI to be viewed. For example, to open the URI web+ap://example.org/@Example in the browser, first extract the domain name and port, in this case example.org, and build an https* URI with them, in this case https://example.org, then add the path to the Well-Known Protocol Handler and navigate to it, resulting in https://example.org/.well-known/protocol-handler?target=web%2Bap%3A%2F%2Fexample.org%2F%40Example.

* Note: This behaviour SHOULD be configurable. At the very least, system administrators SHOULD be allowed to override to http on a per-domain basis, particularly for underlying transport protocols not otherwise recognized as “secure” by modern browsers, such as Tor. See below.

Semantics of the Well-Known Protocol Handler

The Well-Known Protocol Handler SHOULD return a redirect status code for schemes it supports, and redirect the user to a more appropriate view page. However, note the Security Considerations.

A Well-Known Protocol Handler MAY support returning error status codes for schemes it doesn’t recognize or doesn’t support. A Well-Known Protocol Handler SHOULD consistently return the same status code for different URIs with the same scheme. This enables some systems to automatically detect if a given scheme is supported.

Navigating to the Well-Known Protocol Handler

For the purposes of this specification, implementations SHALL use the generic URI syntax as defined in RFC 3986 in order to extract a host and port from a web+* URI. For example: (NOTE: This list is not exhaustive.)

• web+ap://example.org/ -> example.org
• web+ap://example.org:443/ -> example.org:443
• web+ap://foo@example.org/ -> example.org

After extracting the host and port, they can be used to select a Well-Known Protocol Handler for the web+ URI. For example: (NOTE: Also not exhaustive.)

• web+ap://example.org/ -> https://example.org/.well-known/protocol-handler?target=web%2Bap%3A%2F%2Fexample.org%2F
• web+ap://example.org:443/ -> https://example.org:443/.well-known/protocol-handler?target=web%2Bap%3A%2F%2Fexample.org%3A443%2F
• web+ap://foo@example.org/ -> https://example.org/.well-known/protocol-handler?target=web%2Bap%3A%2F%2Ffoo%40example.org%2F

When someone clicks a web+* link in an app, the app MUST either handle it directly (if it’s a link type supported by the app), or find a handler for it. If no handler can be found, the app, or a plugin for the app, SHOULD attempt to open the Well-Known Protocol Handler for the link in the installed web browser. If one or more handlers are found, then they MUST be used, but the app MAY prompt about it and give an opportunity to cancel.

An operating system SHOULD provide a low-priority handler for web+* links. If provided, this handler MUST attempt to open the Well-Known Protocol Handler for the link in the installed web browser. This handler SHALL be used in preference to the corresponding application-level logic, particularly so as to allow a system administrator to override the choice between http and https for certain domains, or for testing purposes.

Prefix Considerations

web+ is de-facto already a prefix. Web browsers do have special rules for the web+ prefix already: it’s the only user-defined URI scheme that is allowed for use in registerProtocolHandler by default. Thus, the authors of this specification believe it is safe to treat it as a prefix for the purposes outlined here.

Security Considerations

The Well-Known Protocol Handler is a simple navigable resource, and the security considerations relevant to any navigable resource apply. Nevertheless, we highlight the following two vulnerabilities and recommendations as being of particular relevance.

Open Redirect

An open redirect attack occurs when an attacker uses an open redirect on a legitimate website in order to trick an unsuspecting user into visiting the attacker’s phishing website.

Due to the nature of the Well-Known Protocol Handler, common mitigations such as checking Referer, Origin, and other headers, are not available here. Where possible, the provided target SHOULD be opened within the scope of the well-known resource, or rejected altogether. Otherwise, the user MUST be notified of scope changes and be given the option to confirm or deny them.

For example, if the Well-Known Protocol Handler at example.org is asked to open a link relating to example.net, it may either:

• Reject it altogether, and show an error page in example.org.
• Open a web-based client in example.org that can render the remote resource.
• Prompt about navigating to the remote resource somehow.

Improper Authorization in Handler for Custom URL Scheme

Some URIs may be used to carry actions. An attacker may include malicious actions in such URLs. Since this endpoint is navigable, an attacker can simply open it, sometimes even without user intervention.

Servers implementing the Well-Known Protocol Handler MUST NOT automatically execute actions based on the `target. Ideally, servers SHOULD reject/ignore these actions altogether, and let the user execute the action in the interface they are presented with, as it’s not uncommon for users to simply click “yes” or “confirm” in an attempt to dismiss prompts. In some cases, for example for message composition URLs (mailto, etc), rejection may simply not be possible; in these cases the server can prompt the user before executing the action.