This document captures requirements to evolve protocol handlers as available on the web. The goal is to make it possible to extend the set of protocols that are supported while maintaining a high level of security and trust for users.

Handlers Beyond Handoff

Protocol handlers today are focused on single-shot handoff. When activating a mailto: link, the browser will either hand it off to the OS for a native application to handle, or will pass it to a (top-level) URL that will receive it as a parameter and process it. In either case, the interaction is not incorporated into the current context and no further interaction with the protocol is possible. In effect, this is more a scheme dispatcher than a comprehensive handler for a given protocol.

Today's on-ramp for new protocols to become used on the web beyond a simple handoff however is too steep. While there is interest from implementers in loosening handler registration, that does not extend to the ability to fully integrate new protocols into the web stack such that they can be the source of top-level documents, iframes, fetch, images, etc.

This document captures requirements for browser extensions to be able to register as full-fledged (or at least fuller-fledged) programmatic protocol handlers. For instance, using this approach an extension could implement support for IPFS directly within any browser context.

Integration

One goal is that registering a protocol handler in different ways and at different levels should map to a unified underlying model to the extent possible, so as to ensure that a single code path controls protocol handling.

With progress towards a IANA+blocklist approach as advocated in whatwg/html#9158, there is no need to limit registration to web+- or ext+-prefixed schemes.

The proposed integration method for new protocol handling is to operate a Service Worker for that protocol that can respond to FetchEvents. The assumption is that the browser will address any and all schemes with HTTP semantics, and it is up to the handler to figure out the appropriate mapping, knowing that there will likely be impedance mismatch.

The current proposal only exposes this capability to extensions. In that context, registering a Service Worker for handling by an extension is done using the protocol_handlers field. We suggest adding a serviceWorker field that points to a JS resource in the extension implementing a Service Worker. The serviceWorker field takes precedence over the uriTemplate field (but having both is not an error, this allows for an upgrade path). (See notes from lidel tracking the idea.)

Note that custom protocol handlers of this kind need to be integrated at the same architectural position as the browser's built-in protocol handling. Notably, they kick in after extension points to block or modify network requests have been processed. If, for instance, an ad blocker has a denylist that includes ipfs: URLs, those will be processed before the IPFS protocol handler is invoked.

In the case of handoff protocol handlers, user agents can simply prompt the user to pick which handler they wish to use after activating a link with a custom protocol. With programmatic handlers that can be called upon to load a subresource, that is not a desirable behavior. In cases where a new handler is being registered for a scheme that there is already a handler for, the user agent is encouraged to pick which one will be used. User agents may simply use the latest handler to be registered, or may prompt the user to select the one they wish to use by default. User agents should avoid having both programmatic handlers and handoff handlers registered for the same scheme as that can create a confusing experience if clicking on a custom protocol link offers to choose between those two but loading a subresource only selects the programmatic one. In such cases, systematically using the the programmatic handler is likely to be the most user-friendly option.

A manifest with a Service Worker handling the protocol looks like this:

        {
          "manifest_version": 2,
          "name": "InterPlanetary Wonders",
          "icons": {
            "48": "planets.png",
            "96": "planets@2x.png"
          },
          "version": "17.0.1",
          "protocol_handlers": [
            {
              "protocol": "ipfs",
              "name": "IPFS Makes Your Browser Fresh",
              "serviceWorker": "js/gateway-loader.js"
            }
          ]
        }
      

And the Service Worker is straightforward:

        self.addEventListener("fetch", (ev) => {
          ev.respondWith(
            (async () => {
              const url = new URL(ev.request.url);
              const gatewayURL = [
                'https://ipfs.io/ipfs/',
                url.hostname,
                url.pathname || '/',
                url.search || '',
                url.hash || '',
              ].join('');
              const { method, headers, body, mode, credentials, cache, redirect,
                referrer, referrerPolicy, integrity, signal } = ev.request;
              return fetch(new Request(
                gatewayURL,
                { method, headers, body, mode, credentials, cache, redirect,
                  referrer, referrerPolicy, integrity, signal }
              ));
            })(),
          );
        });
      

Integration Considerations

In order to plug a protocol as an extension to the browser's capabilities, we need to address more than simply handing a URL off to an API that returns a stream. While it is possible to expose the many options involved through an API, it is easy enough to shoot yourself in the foot and has enough potential security issues that our preference goes to selecting a strict default behavior instead.