{"id":14956148,"url":"https://github.com/ipfs/service-worker-gateway","last_synced_at":"2026-01-16T02:13:22.369Z","repository":{"id":151545883,"uuid":"621947766","full_name":"ipfs/service-worker-gateway","owner":"ipfs","description":"IPFS Gateway implemented in Service Worker","archived":false,"fork":false,"pushed_at":"2025-04-09T15:53:07.000Z","size":37797,"stargazers_count":52,"open_issues_count":27,"forks_count":17,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-09T20:04:15.701Z","etag":null,"topics":["helia","ipfs","ipfs-gateway","ipfs-helia","service-worker","typescript"],"latest_commit_sha":null,"homepage":"https://inbrowser.link","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-31T18:34:49.000Z","updated_at":"2025-04-09T15:52:57.000Z","dependencies_parsed_at":"2024-01-24T21:45:45.546Z","dependency_job_id":"b3bdcc00-7e64-40d7-ad0a-d742122c8613","html_url":"https://github.com/ipfs/service-worker-gateway","commit_stats":{"total_commits":131,"total_committers":10,"mean_commits":13.1,"dds":"0.48091603053435117","last_synced_commit":"3c9b300f4446da1f801d663ac39012287b87574d"},"previous_names":["ipfs/service-worker-gateway","ipfs-shipyard/service-worker-gateway"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fservice-worker-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fservice-worker-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fservice-worker-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs%2Fservice-worker-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs","download_url":"https://codeload.github.com/ipfs/service-worker-gateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103865,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["helia","ipfs","ipfs-gateway","ipfs-helia","service-worker","typescript"],"created_at":"2024-09-24T13:12:23.230Z","updated_at":"2026-01-16T02:13:22.364Z","avatar_url":"https://github.com/ipfs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg src=\"https://github.com/ipfs/service-worker-gateway/blob/ca0a5ad20e5f9aac7a50047cade51f0a2d7a31b0/public/ipfs-sw-icon-512-shadow.png\" alt=\"logo\" title=\"logo\" width=\"200\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  Service Worker IPFS Gateway\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\" style=\"font-size: 1.2rem;\"\u003eDecentralizing IPFS Gateways by verifying hashes in the user's browser.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ipfs.tech\"\u003e\u003cimg src=\"https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square\" alt=\"Official Part of IPFS Project\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discuss.ipfs.tech\"\u003e\u003cimg alt=\"Discourse Forum\" src=\"https://img.shields.io/discourse/posts?server=https%3A%2F%2Fdiscuss.ipfs.tech\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ipfs/service-worker-gateway/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ipfs/service-worker-gateway/main.yml?branch=main\" alt=\"ci\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ipfs/service-worker-gateway/releases\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/github/v/release/ipfs/service-worker-gateway?filter=!*rc*\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003chr /\u003e\n\n## About\n\nThis project demonstrates the use of [Helia](https://github.com/ipfs/helia)\n(IPFS implementation in JS) and the [`verified-fetch` library](https://github.com/ipfs/helia-verified-fetch)\n([Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) for IPFS)\nwithin a [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)\nto facilitate direct verified retrieval of content-addressed data.\n\nA Service Worker is registered on the initial page load, and then intercepts\nHTTP requests for content stored on IPFS paths such as `/ipfs/*` (immutable) and\n`/ipns/*` (mutable) and returns [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)\nobjects to the browser.\n\nIt functions as an IPFS gateway within the browser, offering enhanced security\n([hash verification](https://docs.ipfs.tech/concepts/content-addressing/)\nhappens on end user's machine) and reliability (ability to use multiple sources\nof content-addressed blocks) without reliance on a single HTTP server for IPFS\ntasks.\n\n\u003ca href=\"http://ipshipyard.com/\"\u003e\u003cimg align=\"right\" src=\"https://github.com/user-attachments/assets/39ed3504-bb71-47f6-9bf8-cb9a1698f272\" /\u003e\u003c/a\u003e\n\nThis project  was brought to you by the [Shipyard](http://ipshipyard.com/) team.\n\n### Goals\n\nThe main goals of this project are:\n\n- **Enhancing the robustness of IPFS-based web hosting by eliminating reliance\n  on a single HTTP backend.**\n  - Tasks such as fetching blocks from IPFS content providers (both\n    peer-to-peer and HTTP), verifying that block hashes match the expected CID,\n    and re-assembling blocks into deserialized bytes that can be rendered by\n    the browser, all happens within the end user's machine.\n- **Reducing the operational costs associated with running an HTTP backend.**\n  - By shifting the majority of data retrieval tasks to the user's browser, the\n    backend hosting a website no longer needs to serve as a conduit for all of\n    its data. This means that a gateway operator could potentially run a simple\n    HTTP server on a Raspberry Pi, serving only small static HTML+JS files\n    (\u003c10MiB), while allowing all other operations to occur within the user's\n    browser, with data fetched either peer-to-peer or from remote HTTP\n    trustless gateways.\n- **Improving JS tooling, IPFS specifications, and gateway-conformance tests.**\n   - By having to implement gateway semantics end-to-end we identify bugs and\n     gaps, and improve quality of libraries, specifications, and interop tests.\n\n\n### Feature Set\n\n- 🚧 **WIP:** Web interface for adjusting routing and retrieval settings.\n- 🚧 **WIP:** [Trustless](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) content retrieval from multiple HTTP gateways.\n- 🚧 **WIP:** Support for [Web Gateway](https://specs.ipfs.tech/http-gateways/) feature set for website hosting (`index.html`, [web pathing](https://github.com/ipfs/specs/issues/432), `_redirects`).\n- 🚧 **Future:** [HTTP Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) (`/routing/v1`) client for discovering additional direct content providers.\n- 🚧 **Future:** [Denylist](https://specs.ipfs.tech/compact-denylist-format/) support for operators of public nodes.\n\n## Usage\n\n### Running locally\n\nYou can build and run the project locally:\n\n```console\n\u003e npm i\n\u003e npm run build\n\u003e npm start\n```\n\nNow open your browser and go to `http://localhost:3000`\n\nBelow is an explanation of the different URLs and what they do:\n\nWith reverse-proxy:\n* `http://localhost:3333` - The service worker gateway front-end served directly with esbuild. (localhost:3333 -\u003e localhost:8345)\n* `http://localhost:3334` - The service worker gateway front-end hosted by an IPFS gateway running on 'localhost:8088'. (localhost:3334 -\u003e localhost:8088 with x-forwarded-host header)\n\nWithout reverse-proxy:\n* `http://localhost:8345` - The service worker gateway front-end served directly with esbuild.\n\nFor the above URLs with reverse-proxy, the reverse proxy ensures subdomain\nsupport. This ensures you can access URLs like `https://\u003chash\u003e.ipfs.localhost:\u003cport\u003e/`\nand `https://\u003cdnslink\u003e.ipns.localhost:\u003cport\u003e/`\n\nAs you type in a content path, you will be redirected to appropriate URL\n(typically that means [subdomain style resolution](https://docs.ipfs.tech/how-to/gateway-best-practices/#use-subdomain-gateway-resolution-for-origin-isolation)).\n\nFor more information about local development setup, see [/docs/DEVELOPMENT.md](/docs/DEVELOPMENT.md).\n\n### Try hosted instance\n\nWe provide a public good instance of this projct configured to run in[subdomain mode](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway),\naiming to be a drop-in replacement for `dweb.link`:\n\n- 🚧 **WIP: alpha quality** https://inbrowser.link hosts the `release` branch, with a stable [release](https://github.com/ipfs/service-worker-gateway/releases)\n- 🚧 **WIP: alpha quality** https://inbrowser.dev hosts the `staging` branch with development / testing version\n\nThere is also an instance running in [path mode](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway),\naiming to be a drop-in replacement for `ipfs.io`:\n\n- 🚧 **WIP: alpha quality** https://ipfs-service-worker-gateway.pages.dev hosts the `release` branch, with a stable [release](https://github.com/ipfs/service-worker-gateway/releases)\n- 🚧 **WIP: alpha quality** https://staging.ipfs-service-worker-gateway.pages.dev hosts the `staging` branch with development / testing version\n\n#### Deploying to `production` and `staging`\n\nDeploying to [production](https://github.com/ipfs/service-worker-gateway/actions/workflows/deploy-to-production.yml)\nand [staging](https://github.com/ipfs/service-worker-gateway/actions/workflows/deploy-to-staging.yml)\nis done by manually running the deployment action and passing the release\nversion to the action.\n\n## Manual Service Worker Deregistration\n\nIn some cases, you might want to manually unregister or remove the Helia service\nworker from your browser. This can be useful for debugging purposes or to ensure\na clean state.\n\nYou can instruct the service worker to unregister itself by appending the\n`?ipfs-sw-unregister=true` query parameter to the URL of any page controlled by\nthe service worker.\n\nFor example, if the service worker is active for `https://example.com`,\nnavigating to `https://example.com/?ipfs-sw-unregister=true` will cause the\nservice worker to unregister itself and attempt to reload all controlled clients\n(browser tabs).\n\nThis option is also available via a button on the service worker's configuration\npage (`#/ipfs-sw-config`).\n\n## License\n\nThis project is dual-licensed under `SPDX-License-Identifier: Apache-2.0 OR MIT`\n\nSee [LICENSE](./LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fservice-worker-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs%2Fservice-worker-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs%2Fservice-worker-gateway/lists"}