Google Groups

Intent to Implement and Ship: Additional safelisted schemes for "registerProtocolHandler"

Asanka Herath Aug 30, 2018 2:19 PM
Posted in group: blink-dev

Contact emails


registerProtoclHandler() is a method that “allows Web sites to register themselves as possible handlers for particular schemes” (from whatwg/html). The set of schemes that can be associated with custom handlers is restricted to a safelist and schemes that begin with web+ (whatwg/html#safelisted-schemes).

The current list of Google Chrome’s whitelisted schemes (as of August 27, 2018) can be found here. For your convenience, the current list is: bitcoin, geo, im, irc, ircs, magnet, mailto, mms, news, nntp, openpgp4fpr, sip, sms, smsto, ssh, tel, urn, webcal, wtai, and xmpp.

We are proposing the extension of the safe list with the following schemes:

  • dat, dweb, ipfs, ipns, ssb.

    These are schemes that are used with distributed web protocols. Allowing custom handlers for these schemes aid experimentation of these protocols on Chrome.

  • bzr, bzr+ftp, bzr+lp, bzr+http, bzr+https, bzr+sftp, bzr+ssh, cvs, cvs+ext, cvs+pserver, cvs+ssh, darcs+http, darcs+https, darcs+ssh, git, git+http, git+https, git+ssh, hg, hg+http, hg+https, hg+ssh, hg+static-http, lp, svn, svn+http, svn+https, svn+ssh.

    These schemes correspond to source control protocols along with variants for specifying subprotocols or underlying transports.

  • map, gmap, bingmap, location

    Planned use in provider agnostic map URLs.

  • doi

    Details on Digital Object Identifiers (DOI) can be found at

Design doc/Spec

Spec for registerProtocolHandler is here. Note that no functional implementation change is proposed here other than the extension of the set of customizable schemes.

  • dat, dweb, ipfs, ipns, ssb based on this proposal.

  • bzr, bzr+ftp, bzr+lp, bzr+http, bzr+https, bzr+sftp, bzr+ssh, cvs, cvs+ext, cvs+pserver, cvs+ssh, darcs+http, darcs+https, darcs+ssh, git, git+http, git+https, git+ssh, hg, hg+http, hg+https, hg+ssh, hg+static-http, lp, svn, svn+http, svn+https, svn+ssh based on this proposal.

  • map, gmap, bingmap, location based on this proposal.

  • doi based on this proposal.

The spec explicitly encourages expanding the scheme safelist: "This list can be changed. If there are schemes that ought to be added, please send feedback." As such, developers have made the above proposals, which we're now acting on.

Skipping TAG review since this proposal is for custom schemes whose functionality is left up to applications.


Extend list of URL schemes that can be overridden via registerProtocolHandler().


Extending the list to include version control, mapping, DOI, and decentralized web protocols allows resolution of links to generic entities independently of the website or gateway that’s providing access to it.

For example, ipfs:QmT9qk3CRYbFDWpDFY could be a URL for a resource on IPFS (Note.: The example URL is not a valid IPFS URL). The process of resolving the URL to bytes may be performed via a local IPFS gateway at http://localhost:8080/ipfs#ipfs:QmT9qk3CRYbFDWpDFY or via a web gateway at https://ipfs.gateway.example/ipfs#ipfs:QmT9qk3CRYbFDWpDFY.

If ipfs was a whitelisted scheme, then either http://localhost:8080 or https://ipfs.gateway.example/ipfs could request permission to handle ipfs: links. Furthermore, anyone can publish links to resources under IPFS using ipfs: links regardless of the user’s choice of gateway. Currently there’s no portable mechanism to make navigations to ipfs: URLs work without friction.


Interoperability and Compatibility

Adding support for more custom schemes does not pose a compatibility risk with existing pages since none should depend on being able to register handlers for hitherto disallowed schemes.

Google Chrome, Mozilla Firefox, and Opera are the only browsers that currently implement registerProtocolHandler. Chrome and Firefox gate registration of scheme handlers by web pages as per spec. In addition, Firefox allows WebExtensions to register handlers for distributed web schemes (see Firefox’s WebExtensions protocol_handler safelist here).

The following risks exist:

  • User confusion with standard schemes. This could be an issue for the version control schemes that have protocol suffixes that are standard schemes, namely http and https.

    While these URLs could be exposed to the user via mouse hover over links or displayed inline, the URLs themselves don’t appear in the omnibox. Google Chrome and Firefox both handle custom protocols as redirects. The URL shown in the address bar is the rewritten URL and not the custom scheme, thus mitigating the possibility of spoofing.

    In the case of distributed web protocols, we are aware that the developer community desires custom URLs to be displayed in the omnibox, as well as being used for fetching subresources. Google Chrome has no current plans to implement this behavior.

  • Insufficient uptake of a scheme. While developers have expressed interest, metrics will ultimately tell us whether there’s sufficient uptake of each scheme. The incremental overhead for browser is trivial, though every bit counts.

  • Ossification of unspecified schemes. Some of the URL schemes being proposed for addition do not have a public specification, mature or otherwise. It is possible that one or more early adopters will prematurely define the URL scheme by their implementation. Whilst unfortunate, developers should assume this risk rather than the UAs.

  • Conflicts with native support. Popular browsers in the future may, and specialized browsers currently do, implement native support for some of the distributed web protocols. Where native support for a protocol exists, the corresponding scheme will need to be removed from the safelist for each respective browser, and eventually from the spec. We believe that native support for a protocol would not reduce functionality for users and hence such a change would not be disruptive.

  • Scheme creep. “If scheme x is included, then why not scheme y?” might be a question we’ll soon need to deal with. This I2IS focuses only on schemes that were requested by developers.

Edge: No signals (does not implement registerProtocolHandler)

Firefox: Adding distributed web schemes (i.e. dat, dweb, ipfs, ipns, ssb) to safelist is being discussed here. Firefox allows WebExtensions to register themselves as handlers for these schemes since 59 (See compat table here and this issue). No signals for supporting other schemes.

Safari: No signals (does not implement registerProtocolHandler)

Web developers: All proposals are based on requests made by developers. For the distributed web schemes, see


No additional considerations beyond those for registerProtocolHandler.


No additional considerations beyond those for registerProtocolHandler. The HTML spec will be updated concurrently to reflect changes to the safelist.


No additional considerations beyond those for registerProtocolHandler.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?


Is this feature fully tested by web-platform-tests?

Tests exist for registerProtocolHandler (here) which verify that all whitelisted schemes are overridable. Once approved, the schemes proposed here will be added to that list.

Link to entry on the feature dashboard (Distributed web schemes) (Others)

Requesting approval to ship?