Service Worker IPFS Gateway

Decentralizing IPFS Gateways by verifying hashes in the user's browser.

---

About

This project demonstrates the use of Helia (IPFS implementation in JS) and the verified-fetch library (Fetch API for IPFS) within a Service Worker to facilitate direct verified retrieval of content-addressed data.

A Service Worker is registered on the initial page load, and then intercepts HTTP requests for content stored on IPFS paths such as /ipfs/* (immutable) and /ipns/* (mutable) and returns Response objects to the browser.

It functions as an IPFS gateway within the browser, offering enhanced security (hash verification happens on end user's machine) and reliability (ability to use multiple sources of content-addressed blocks) without reliance on a single HTTP server for IPFS tasks.

This project was brought to you by the Shipyard team.

Goals

The main goals of this project are:

• Enhancing the robustness of IPFS-based web hosting by eliminating reliance on a single HTTP backend.
  • Tasks such as fetching blocks from IPFS content providers (both peer-to-peer and HTTP), verifying that block hashes match the expected CID, and re-assembling blocks into deserialized bytes that can be rendered by the browser, all happens within the end user's machine.
• Reducing the operational costs associated with running an HTTP backend.
  • By shifting the majority of data retrieval tasks to the user's browser, the backend hosting a website no longer needs to serve as a conduit for all of its data. This means that a gateway operator could potentially run a simple HTTP server on a Raspberry Pi, serving only small static HTML+JS files (<10MiB), while allowing all other operations to occur within the user's browser, with data fetched either peer-to-peer or from remote HTTP trustless gateways.
• Improving JS tooling, IPFS specifications, and gateway-conformance tests.
  • By having to implement gateway semantics end-to-end we identify bugs and gaps, and improve quality of libraries, specifications, and interop tests.

Feature Set

• 🔒 Trustless Retrieval client that fetches content directly from providers over HTTPS, Secure WebSockets, and other browser-compatible transports, using a fallback trustless gateway when direct retrieval is not possible.
• 🌐 Service Worker running as a Web Gateway for website hosting (index.html, web pathing, _redirects).
• 🧭 HTTP Routing V1 (/routing/v1) client for discovering content providers (via delegated-ipfs.dev).
• 📡 DNSLink resolution via DNS-over-HTTPS (DoH).

Compliance with IPFS HTTP Gateway specifications is tested using the gateway-conformance test suite (the same suite used by Kubo and Rainbow).

Browser support

The gateway supports recent versions of all major web browsers.

It is built using modern Web APIs so needs a web browser kept up to date with the latest features and security patches.

If you see a notice asking you to update your browser, please do so.

Usage

Running locally

You can run the project locally:

> npm install
> npm start

Now open your browser and go to http://localhost:3000

The gateway runs exclusively in subdomain mode -- as you type in a content path, you will be redirected to an appropriate subdomain URL with Origin isolation.

For more information about local development setup, see ./docs/DEVELOPMENT.md.

Try hosted instance

We provide a public good instance of this project configured to run in subdomain mode, aiming to be a drop-in replacement for dweb.link:

• https://inbrowser.link -- production, deployed from tagged releases
• https://inbrowser.dev -- staging, deployed from tagged pre-releases

For deployment details, see docs/DEVELOPMENT.md.

Manual Service Worker Deregistration

In some cases, you might want to manually unregister or remove the Helia service worker from your browser. This can be useful for debugging purposes or to ensure a clean state.

You can instruct the service worker to unregister itself by appending the ?ipfs-sw-unregister=true query parameter to the URL of any page controlled by the service worker.

For example, if the service worker is active for https://example.com, navigating to https://example.com/?ipfs-sw-unregister=true will cause the service worker to unregister itself and attempt to reload all controlled clients (browser tabs).

License

This project is dual-licensed under SPDX-License-Identifier: Apache-2.0 OR MIT

See LICENSE for more details.