# IPFS in Browsers

## Contributing to this document

Are you using (or plan to use) JS-IPFS in browser ? Your input would really help in shaping the plan which we hope will improve your and your users experience with IPFS. You can help by:

- Asking a question in [Q&A](#QampA) section.
- Providing your feedback in [ipfs/js-ipfs#3022][].

## Vision

We would like JS-IPFS to deliver great experience in Browsers for both developers that use it and users of the IPFS network (users using developed web applications that use IPFS). Ideally this would translate into following

#### Network optional

Applications developed with IPFS do not reqire network to read / write data. More specifically, file saved by awesome notebook app (e.g peerpad) should be accessible via another awesome app locally, whithout having to upload & download that content over the internet.

#### Full control of IPFS

Users of IPFS are in full control of their IPFS. Canonical view through which all user data can be accessed / shared regardless of interface (or app) this data was added / created.

This is true not only across system / web applications but also across user devices (although this would need to be another endeavour).

This also implies that IPFS node ultimatly acts on user behalf as opposite to app behalf.

#### Just Works^TM^

Developers are not required to figure out best configuration, make choice between providers or deal with fallbacks. IPFS node just adapts to the system constraints and seamlessly takes advantage of capablities that are available (e.g if IPFS Desktop is running in-browser node seamlessly upgrades it's capablities like local discovery).

#### IPFS Node (instead of nodes)

Browsers come with IPFS built-in, in fact browser is IPFS node _(or rather interface to the operating system node)_. Until then JS-IPFS in browser is a [polyfill][] for it. This implies single IPFS used by all the browser tabs which takes care of access management and permissions just like browser does with other resources.

## Problem Statement

JS-IPFS project started back when web platform had significant limitations, so it naturally evolved around [Node.js][] ecosystem. Web platform has matured quite a bit since, JS-IPFS is used in browsers these days, however some technical decisions that make perfect sense in [Node.js][] runtime lead to suboptimal results in browser environment.

##### Many ~~tabs~~ IPFS nodes

Most people have many tabs open in browsers. If each tabs used IPFS, users would end up with same number of many IPFS nodes running as they have tabs, each competing for resources, establishing many network connections and crunching through battery in the process.

##### Local data over the network

Another surprising and not sometimes not very obvious side effect is that content from one tab may _only_ be fetched by the other over the internet _(It is not the case when tabs share [origin][] as they would share storage)_. Which is obviously wasteful and in some instances may not even work due to network conditions.

## Improvement Proposal

Web security model is based around origin policies. In practical terms browsing contexts (tabs, iframes, workers) with **same origin** are sharing access same resources & capabilities. Browsing contexts **cross origin** are sandboxed from each other and are only able to communicate with each other through message passing. These differences demand different strategies for same origin and cross origin.

### Same Origin

In order to share JS-IPFS node across multiple browsing contexts with the same origin they can use a [`SharedWorker`][] API to operate shared JS-IPFS node. JS-IPFS embedder will interface with `IPFSClient`, that is similar to [js-ipfs-http-client][] as it would provide JS-IPFS compatible API for the IPFS node in the `SharedWorker`. `SharedWorker` will be running `IPFSService` that will service incoming requests from `IPFSClient` via (potentially trimmed down) JS-IPFS node also running in the `ServiceWorker`.

declare class IPFSClient extends IPFSInterface {
  /**
   * Connects to remote IPFSService.
   * @param {MessagePort} port Port represeting connection to the IPFSService
   */
  static connect(port:MessagePort):IPFSController
  /**
   * Creates SharedWorker with IPFSService and connects to it.
   * @param {string} url URL for the ipfs worker bundle.
   */
  constructor({url:string})
}

#### Constraints / Tradeoffs

It would be great to make all the improvements and everything API compatible. However there are several unique constraints that make this impossible.

##### Distribution / Bundling

Use of workers complicates distribution / bundling because some code (client) needs to be loaded in the main thread and some code (service) in the worker thread. Furthermore to allow opt-out from worker setup would require loading both parts in the main thread.

In order to keep things simple client / service parts will be broken apart, allowing users to choose preferred bundling strategy that fits their use case best. Additionally alternative distribution will be created that will load service via embedded blob url.

##### Configurability

Today JS-IPFS is highly configurable. But when multiple tabs share same IPFS node they have no choice but to share configuration as well. It is also a challenge facing [native IPFS support in browsers][] and a challenge that came up on desktop as well.

**Community input is required to understand what configuration options are used in the wild**

General assumption is that configurability can be traded for simplicity and improved resource usage.

[Discussion on configuration options][config discuss].

##### WebRTC Transport

WebRTC is not yet supported by browsers in worker contexts, making WebRTC transport impossible to support. This is a serious tradeoff that we hope to overcome in the future (e.g. we may explore mapping `RTCDataChannel` to `MessagePort` and providing access that way).

##### Safari Support

Safari is only mainstream browser that does not support [`SharedWorker`][] API making it impossible to keep node alive for the duration of the longest living browsing context for the origin. There for initially Safari will continue to have a node per tab. In the future however we will explore ways to overcome this limitations e.g. via [`ServiceWorker`][] API.

### Cross Origin

In order to share IPFS node across browsing contexts on different origins we would need to employ message passing APIs. Given that same origin work is designed around `IPFSClient` and `IPFSService` communicating over `MessagePort` it is possible to have them across different origins.

However somehow there will need to be a single origin hosting `IPFSService` piece that `IPFSClient`s across origin will connect to. To do this cross-origin `IPFSClient`s will create a (hidden) `iframe` loading `JS_IPFS_SERVICE` URL into it. Document inside iframe will spawn `IPFSService` in `SharedWorker` and connect its `port` to an `IPFSClient`.

In order to avoid centralization around some `JS_IPFS_SERVICE` we can take advantage of [`navigator.registerProtocolHandler`][] API. And use `web+ipfs-origin://` URL instead allowing user to choose between different origins improving resilience.

#### Constraints / Tradeoffs

There are few additional constraints on top of the ones that same-origin node sharing imposes.

##### Upholding origin isolation

Browsers isolate content storage by origin for a good reasons, you don't want to enable malicious app to have full access to all of your data. To address this shared node would need to also need to isolate content & pins by origin.

##### DOM Requirement

In order to facilitate cross-origin message passing and to ensure that `SharedWorker` remains alive for the duration of `IPFSClient`, iframe element need to be kept in the document tree.

This is not necessarily a bad thing, in fact if node is shared across multiple origins it would be necessary to mediate access control. Having an iframe on separate origin would enable doing it safely without having to trust embedder.

## Q&A

_It is impossible to capture everything in the proposal. Please use this section to ask any questions / find answers to details not captured in the proposal_

- Protocols registered via `navigator.registerProtocolHandler`redirect to other URL. Is that works for iframes ?
- Yes, iframe will just load redirected document.
- Registering protocol implies user prompt on the very first page load, what would happen if user refuses?
- Yes there will have to be user interaction to allow choice. [Webactions][] use this [mechanism][index-config] in the wild to allow [indieweb][] social interactions we can learn from them.
- I imagine `IPFSClient` could do a fallback if no handler is registered & onboard user by explaining that there are multiple providers to choose from (ideally also explain how this helps with censorship) and allow hopefully get users to accept. If user chooses not to I think we're have to respect that and maybe have node opperate only locally.

[webactions]:https://indieweb.org/webactions
[index-config]:https://indieweb.org/indie-config
[indieweb]:https://indieweb.org/
- Is `IPFSClient`+`IPFSService` setup "another [provider][ipfs-provider]" like [ipfs-http-client][] and embedded [js-ipfs][] ?
- Don't think so. Ideally `JSIPFS = IPFSClient + IPFSService` where `IPFSService = IPFSDesktopBridge + EmbeddedJSIPFS`. In other words users should use IPFS which makes best use of resources be those CPU / Memory or Companion Apps/Extensions or Remote IPFS Node.

However there are many assumbtions and even if they are valid it will take many iterations to get there. Short term it could be a best way to kick things off.

- How is origin separation going to work ?
- There is more investigation to be done. However I think iOS [filesystem sanboxing][iOS FS Overview] sets good precedent:
- Each application has own view of filesystem.
- Apps can access files from other apps via user interaction (on apps request user can picks any file across the system).

- Are pins going to be origin separated as well ?
- [New IPFS Pinning API][] may have pin associated metadata. It seems that origin associating origin would make sense.

- Does that many MFS or single MFS ?
- Needs research to asses all the tradeoffs. That being I think [iOS filesystem][iOS FS Overview] delivers good exprience that we should aim for (regardless of implementation details):
- User can see all the data across apps
- Apps see only their data + one user explicitly provided.

- Is there a privacy concern here?
- If multiple origins share the same node, they'll share the same peer id which makes them trackable between websites. If they share the system node too that makes them trackable outside of the browser context too.
- Who is the attacker here (as in who is doing the tracking) ?
- Is your peer ID exposes you to a larger attack vector than your network address ?
- Is peer ID rotation more adequate solution for preventing this ? (that is what airdrop seems to do)
- I think privacy is general concern with p2p systems that use DHTs ([hashmatter][] is doing research in this area).
- Ads on pages could technically use your `peer ID` to identify and track you across sites (like cookies are used today).
- This could be addressed by not revealing your peer ID to the scripts on the web. Or alternatively by deriving peer ID from the origin so that could not be used across sites.

- How will this affect JS-IPFS PubSub?
- Will the RTCDataChannel-over-MessagePort option also cover PubSub?
- Will the "trimmed-down" IPFSClient set-up per-page LibP2P instances with PubSub in the meantime?

[iOS FS Overview]:https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html

[New IPFS pinning API]:https://ipfs.io/ipfs/QmUQjFpjZYJYNTbpubBHwwgC12iup1ogQv3d8dBXxzjCq6/ipfs-pinning-api.compressed.pdf

[Node.js]:https://nodejs.org/en/ "JavaScript runtime built on Chrome's V8 JavaScript engine."

[origin]:https://developer.mozilla.org/en-US/docs/Web/API/Document/origin

[ipfs/in-web-browsers#158]:https://github.com/ipfs/in-web-browsers/issues/158

[`BroadcastChannel`]:https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API
[`MessagePort`]:https://developer.mozilla.org/en-US/docs/Web/API/MessagePort
[`SharedWorker`]:https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker
[worker]:https://developer.mozilla.org/en-US/docs/Web/API/Worker
[worker-loader]:https://webpack.js.org/loaders/worker-loader/
[js-ipfs-http-client]:https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client
[`ServiceWorker`]:https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers
[ipfs-companion]:https://github.com/ipfs-shipyard/ipfs-companion
[native IPFS support in browsers]:https://blog.ipfs.io/2019-10-08-ipfs-browsers-update/
[`navigator.registerProtocolHandler`]:https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler
[ipfs-provider]:https://github.com/ipfs-shipyard/ipfs-provider
[js-ipfs]:https://github.com/ipfs/js-ipfs
[ipfs-http-client]:https://github.com/ipfs/js-ipfs/tree/master/packages/ipfs-http-client
[polyfill]:https://developer.mozilla.org/en-US/docs/Glossary/Polyfill
[config discuss]:https://github.com/ipfs/js-ipfs/issues/3042
[hashmatter]:https://hashmatter.com/
[ipfs/js-ipfs#3022]:https://github.com/ipfs/js-ipfs/issues/3022