The Fedi Links Project exists to promote and support federated and decentralized protocols. In order to achieve this goal, the Project aims for feature parity with existing cross-silo interactions. One particularly popular way in which interactions across silos occur is through link preview cards. This specification defines link preview cards for web+* links, as otherwise migrating to web+* (for example, web+ap, for ActivityPub instances) would lose the preview cards, causing an UX regression.
This specification builds upon Browsing Behavior of web+* Links, as well as existing cross-silo link preview cards, particularly OpenGraph metadata. However, no particular metadata protocol is enforced by this specification; OpenGraph just appears to be the most popular of them.
The Well-Known Protocol Handler, as defined in Browsing Behavior of web+* Links, can be used to retrieve OpenGraph or other metadata for link preview purposes. When processing a web+* link, convert it to the Well-Known Protocol Handler before passing it on to the preview card fetching code.
This specification carries no new security considerations than those already relevant to existing link preview systems.
]]>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.
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, 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.
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.
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.
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.
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.
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:
example.org
.example.org
that can render the remote resource.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.
]]>The web+ap
URI scheme is intended to represent web-based ActivityPub objects,
as seen in the ActivityPub specification.
Same as https
, with the following additional restrictions:
See RFC9110, Section 4.2.2 for https
.
Same as https
.
Currently, none of the ActivityPub implementations parse web+ap
URIs. There
is an open redirector that parses web+ap
URIs and turns them into the correct
https
URI, on a best-effort basis.
It is worth noting that browsers parse these using the WHATWG URL spec, especially when used as e.g. a web-based protocol handler.
This specification was explicitly designed with Browsing Behavior of web+ Links, by the Fedi Links Project in mind.
A web+ap
URI is an https
URI with additional semantics. ActivityPub software
supporting this URI MUST treat it as an https
URI and then follow the
ActivityPub specification, especially when it comes to the exchanged content
types (the Accept
and Content-Type
header).
It is also encouraged for operating systems to provide a fallback mechanism for these URIs. This SHOULD be done in a way that the target website can reject non-ActivityPub objects (like invite links). This fallback mechanism SHOULD be used when no appropriate ActivityPub software is available.
The security considerations are basically the same as https
, with additional
considerations for this being a valid scheme for registering a web-based
protocol handler. The purpose of this URI is to explicitly allow registering
a web-based protocol handler, particularly one of the user’s choice, for
interacting with the ActivityPub network. More specifically, this would allow
the user to use their own e.g. Mastodon instance to interact with ActivityPub
URIs, automatically.
No further security considerations are currently known.
]]>