Introduction

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.

Background

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.

Generating the preview cards

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.

Security Considerations

This specification carries no new security considerations than those already relevant to existing link preview systems.

O URI scheme web+feed representa um feed do tipo Atom.

Sintaxe

A mesma que https, mas com as seguintes restrições:

1. Userinfo é proibído. A presença de userinfo deve ser tratada como um erro.

Ver RFC9110, Seção 4.2.2 para https.

Considerações de codificação

As mesmas que https.

Considerações de interoperabilidade

Vale notar que navegadores processam esses URIs de acordo com WHATWG URL spec, principalmente quando utilizados com um tratador de protocolos.

Essa especificação foi explicitamente desenvolvida para ser utilizada com Browsing Behavior of web+ Links, pelo Projeto Fedi Links.

Descrição funcional

Um URI web+feed é um URI https com algumas restrições adicionais e um propósito específico. Um leitor de feeds que é compatível com feeds do tipo Atom e atende a essa especificação deve dereferenciar URIs web+feed através do protocolo HTTPS, da mesma maneira que um URI https. O leitor deve aceitar somente recursos do tipo Atom e deve rejeitar respostas que não são do tipo Atom.

É recomendado que sistemas operacionais possibilitem que esses URIs sejam abertos mesmo que nenhum leitor de feeds esteja instalado, de acordo com Browsing Behavior of web+ Links, pelo Projeto Fedi Links.

Considerações de segurança

Nenhuma consideração de segurança é atualmente conhecida, além daquelas comuns a todos URIs.

Websites/services with a Well-Known Protocol Handler

• is-a.cat (web+ap) by @ar@is-a.cat
• soniex2.autistic.space (web+feed) by @SoniEx2@chaos.social

Software with browsing behavior for web+*

None yet!

Software with web+ap handler

• @tokodon@kde.social
• @Tuba@floss.social
• @Feditext@fedi.software

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.

The web+ap URI scheme is intended to represent web-based ActivityPub objects, as seen in the ActivityPub specification.

Syntax

Same as https, with the following additional restrictions:

1. Userinfo is reserved for future use, and unless otherwise specified, MUST be ignored.

See RFC9110, Section 4.2.2 for https.

Encoding considerations

Same as https.

Interoperability considerations

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.

Functional description

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.

Security considerations

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.

The Fedi Links Project is a collaborative project to make fedi interactions less confusing. We want links to remote posts and accounts to open the posts and accounts, allowing immediate interaction without the need for copying and pasting.

We believe Protocol Handlers are the only viable solution to this problem, at least in the context of the Web as it exists today. We seek to adapt them to real-world use-cases and promote their deployment.

Manifesto

The Fedi Links Project is a bottom-up project.

We want IRC clients, Matrix clients, terminal emulators, multiplayer games, game engines, Mastodon apps, and other user-facing software to add support for Fedi Links.

There are many apps, but not many OSes. Many of those are cross-platform and work across multiple OSes. They should support Fedi Links on all of them.

OSes like Windows and macOS do not need to support Fedi Links if apps can support Fedi Links instead. We assume Windows and macOS are unlikely to support Fedi Links, but the bottom-up approach means we do not need them to.

Specifications

Governance

The Fedi Links Project is operated like a leather bar. Come on in, share stories, hang out, etc.

Code of Conduct

We do not currently have a code of conduct as all of the popular code of conducts have been shown to be unsuitable. None of them acknowledge the pervasiveness of racism and how it shapes and forms the way our communities are built.

We are, however, open to discussions on this topic. Feel free to bring any proposals and other materials relating to Code of Conduct to our IRC channel.

Join us

Find us on IRC: #fedilinks at libera.chat. (Or read the public IRC logs.)

Talks

• BlanketCon 23: Protocol Handlers

Feature Matrices

License

The project is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.