Skip to content

ipfs/service-worker-gateway

Repository files navigation


logo
Service Worker IPFS Gateway

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

Official Part of IPFS Project Discourse Forum Matrix ci GitHub release


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.

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

  • 🚧 WIP: Web interface for adjusting routing and retrieval settings.
  • 🚧 WIP: Trustless content retrieval from multiple HTTP gateways.
  • 🚧 WIP: Support for Web Gateway feature set for website hosting (index.html, web pathing, _redirects).
  • 🚧 Future: HTTP Routing V1 (/routing/v1) client for discovering additional direct content providers.
  • 🚧 Future: Denylist support for operators of public nodes.

Usage

Running locally

You can build and run the project locally:

> npm ci
> npm start

Now open your browser at http://sw.localhost:3000

As you type in a content path, you will be redirected to appropriate URL (typically that means subdomain style resolution).

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

Try hosted instance

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

There is also an instance running in path mode, aiming to be a drop-in replacement for ipfs.io:

Updating production and staging

Make a PR to the respective branch. Once it is merged, new version will be deployed. The process takes between 1 and 5 minutes.

License

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

See LICENSE for more details.