Skip to content

Latest commit

 

History

History
257 lines (192 loc) · 14.9 KB

protocol-handler-api-for-browser-extensions.md

File metadata and controls

257 lines (192 loc) · 14.9 KB
Raw

Targeted Grant: Native Protocol Handler API for Browser Extensions

Issuer: @lidel and @autonome

Project Description

Browser extensions are unable to register handlers for URIs such as ipfs://<cid>

This grant aims to create a new API that enables browser extension to register a native protocol handler capable of returning streaming responses without redirecting to a third party server.

Value

Decentralization: a generic Protocol Handler API could be used by IPFS and other protocols such as Dat and Secure Scuttlebutt.

Local and Offline: browser extension developers could create more powerful extensions running locally without the need for third party localhost apps or web services for out of band processing and workarounds. Bringing back some of possibilities that went away when Mozilla deprecated XUL-based extension ecosystem, but doing so within a well-defined, Origin-based security sandbox.

IPFS: native protocol handler API would enable IPFS Companion browser extension to return data fetched from IPFS network without the need for running a local HTTP Gateway. It would provide same addressing and Origin isolation with embedded js-ipfs as with go-ipfs running on localhost. Origin would not be tied to HTTP transport, but based purely on the root CID, enabling seamless transition between IPFS backends while leveraging integrity guarantees of content addressing.

Deliverables

  • Vendor-agnostic API specification
  • Chromium/Blink implementation

Recommended Team

Igalia is an open source consultancy specialized in the development of innovative projects and solutions, including the web platform.

They are experienced contributors to major browser engines familiar with both codebases and standardization processes. One of most prominent success stories is CSS Grid, which they championed and implemented in Blink and WebKit.

On the IPFS side, grant will be supported by @lidel and @autonome.

Detailed Requirements & Constraints

This grant tries to build on top of what is already possible, pushing web platform and browser extensions forward.

Below we describe the current state of the platform and prior art around protocol handlers in browser extensions.

Finally, we describe what is missing and in separate section list acceptance criteria for this grant.

Prior art: Web API for registering redirect-based handlers

A generic Web API for registering custom protocol handler exists (navigator.registerProtocolHandler), but it is heavily limited.

navigator.registerProtocolHandler('web+ipfs',
                                  'https://example.com/?uri=%s',
                                  'IPFS handler')

Above example:

  • Works only when executed on matching Origin
    • User needs to be on example.com for registration to work
    • Displays user prompt, asking for confirmation if a handler should be registered
  • Requires unknown protocols names to be prefixed with web+ (registerProtocolHandler#Permitted_schemes)
  • In the end, is just a gloried HTTP redirect
    • opening web+ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi will redirect to a web-based handler at http://example.com?uri=web%2Bipfs%3A%2F%2Fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Prior art: browser extension registering a redirect-based handler

Firefox: manifest.json/protocol_handlers

Since Firefox 59 it is possible for a browser extension to perform navigator.registerProtocolHandler-like handler registration during own install by defining handled URI schemes upfront in manifest.json/protocol_handlers.

This automatically registers a redirect-based protocol handler when browser extension is installed and supports DWeb schemes, such as ipfs:// and ipns:// without web+ prefix (whitelisted in bug 1428446).

It removes the need for user to visit specific website, but remains a thin wrapper on top of navigator.registerProtocolHandler API, with the rest of its limitations: it is impossible for a browser extension to return a byte array representing response for requested URL.

This API is not supported by Chromium (bug 883274).

Prior art: browser extension registering a native handler

Muon-based Brave

Before Brave switched to Chromium in 2018, we got basic experimental protocol handler working in Muon. It did not support streaming but was an important milestone for IPFS project. Details can be found in ipfs-companion/issues/312.

Firefox Nightly + libdweb

IPFS, Dat and others collaborated with Mozilla on prototyping native protocol handler under project called libdweb. Old libdweb experiments produced PoC Protocol API and we got PoC extension using the API to work, unfortunately those APIs remained experimental and did not land in regular Firefox Nightly. Over time, Gecko codebase moved forward breaking the demo in latest Nightlies.

There was an effort to reimplement an async iterator version of the PoC Protocol API in the upstream codebase (bug 1271553), but it does not seem to be a priority for Mozilla at this time.

Prior art: Opera's native ipfs:// URI backed by a Subdomain Gateway

Opera for Android 57 shipped native support for ipfs:// and ipns:// URIs. It introduced a custom protocol handler that translates requests made to ipfs:// to a URL at a public subdomain gateway. This way each content root loaded from IPFS gets a unique Origin and is sandboxed from other ones.

While the implementation done by Opera did not use browser extensions, the similar approach (native ipfs:// backed by HTTP gateway) could be leveraged in other browsers if we empower extensions with capability to register custom protocol handlers.

Next: native protocol handler API for browser extensions (this grant)

The work in scope of this grant is to leverage lessons from the past experiments and create a general purpose Protocol Handler API that can be used by any browser extension. Majority of browser vendors support a variant of Chromium's Manifest V2 browser extensions (Firefox calls them WebExtensions). Chromium-based vendors are vocal about being interested in improving IPFS support. To maximize the value created by this grant Chromium codebase should be used as implementation target.

If possible, the API should be compatible with manifest.json/protocol_handlers API already present in Firefox (registering handler on extension install) but with option to omit uriTemplate and provide a self-hosted, programmatic handler via to-be-created chrome.*.registerProtocol API instead.

See Milestones and Acceptance Criteria for more details.

Milestones & Funding

Estimated Funding Amount: 36000 USD (based on hours agreed between Igalia and Protocol Labs)

Note: due to the nature of this exploratory grant, in the event of a Milestone landing being blocked completely before the completion of the full hours, the billing may be under the estimated total and grant recipient will bill only hours worked.

Milestones:

Milestone No. Milestone Description
1 Enhance registerProtocolHandler() to whitelist ”ipfs” and ”ipns” protocols
2 Support protocol_handlers key in Chromium extensions
3 Implement a native protocol handler API for browser extensions

Acceptance Criteria

Milestone 1: Enhance registerProtocolHandler() to whitelist ”ipfs” and ”ipns” protocols

Milestone 2: Support protocol_handlers key in Chromium extensions

  • Coordinate with Microsoft and Google on this proposal, in particular: MicrosoftEdge/MSEdgeExplainers#280 MicrosoftEdge/MSEdgeExplainers#230
  • Ensure that at least the ”ipfs” and ”ipns” protocols are allowed.
  • Make any change to Mozilla’s implementation if necessary
  • Analyze code and get in touch with Chromium’s community to understand the process to extend https://developer.chrome.com/extensions, propose a new API, how they are used in Chromium-based browsers other than Chrome, if a runtime flag is needed, etc.
  • Write PoC patches adding support for this in Chrome’s extensions.
  • Submit patches upstream and land them, with any extra tasks suggested by reviewers to get this accepted (e.g. installation prompt for security, tests, etc).

Milestone 3: Implement a native protocol handler API for browser extensions

  • API specification is approved by IPFS project
    • Origin is based on the content root
    • supports streaming responses by means of async iterators
    • reuses HTTP semantics for caching, content type, headers and error codes
    • likely similar to libdweb’s proposal and an extension of protocol_handlers from task Milestone 2.
  • API implementation in form of patches for Chromium codebase
    • experimental build to test integration with IPFS Companion browser extension
    • allows JS running in browser extension context to register ipfs:// and ipns:// protocol handlers, process every request made with them and return arbitrary bytes
  • API proliferation
    • released under PL's Permissive License Stack or a license suggested by the Chromium project
    • discussed with Microsoft, Mozilla and Chromium projects
    • patches can be integrated into the codebase of other Chromium-based browsers such as Edge or Brave.
    • patches submitted to the upstream Chromium / Blink projects

Resources

Additional resources that might be helpful for an implementer who is working on this project.

Support and Funding

This grant is sponsored by Protocol Labs.