feat(chromium): add `protocol_handlers` manifest key
[!IMPORTANT] This is parked until Chromium ships with
protocol_handlerssupport for Manifest V3 browser extensions.For now, this PR can be used for testing (build extension and load into a test build from Igalia). TBD when we ship it – we will coordinate with Igalia.
Summary
This PR adds protocol_handlers manifest key to the Chromium build, preparing IPFS Companion for native protocol handling of ipfs://, ipns://, and dweb:// URLs.
This aligns the Chromium manifest with Firefox, which has supported protocol_handlers since 2017. Chrome currently ignores unknown manifest keys, so this change is safe to ship now and will activate automatically if/when Chrome implements the feature.
- Related: #164
What this enables
Once Chrome ships the protocol_handlers API, users will be able to:
- Click
ipfs://links and have them handled by IPFS Companion - Type
ipfs://bafy...directly in the address bar - See IPFS Companion listed in
chrome://settings/handlers - TBD if subresources can use
ipfs://(test page:ipfs://bafkreia72r46hbyeozencwzmb7drksaxwg7cqve6wsor336eo72nkklnki)
Implementation notes
- Copies
protocol_handlersconfig frommanifest.firefox.jsontomanifest.chromium.json - No JS changes needed - handler code already exists in
ipfs-request.js - Uses redirect-based handlers via
dweb.link(same as Firefox)
Status
The protocol_handlers API is not yet supported in Chrome stable. Igalia is actively working on bringing this feature to Chromium, and we hope to see it land sometime in 2026, though there's no clear ETA yet.
This PR gets Companion ready and available for testing in dev builds of Chromium that include the prototype:
- Design doc: The protocol_handlers Web Extension's Manifest key
- Chromium CL: protocol_handlers for WebExtensions
Background: Igalia's multi-year effort
We've been collaborating with Igalia since 2022 to bring this capability to Chromium:
2022: Foundation work
- Explainer: Predefined Custom Handlers + Chromium discussion
- SchemeRegistry patch merged
- Demo: IPFS handlers in 2 lines of code
- Blog: New Custom Handlers component for Chrome
2023-2025: WebExtensions API
- Defined the long term North Star: ServiceWorker-like protocol handlers
- Redirect-based prerequisite implementation:
Why this matters beyond IPFS
Igalia designed this as a vendor-agnostic WebExtensions API, not an IPFS-specific feature. Any extension will be able to register custom protocol handlers. This benefits decentralized protocols (IPFS, DAT, SSB, Bitorrent, Bluesky/ATProto, etc.), application deep-linking, enterprise tools, and any future protocol needing browser integration.
Next steps
This redirect-based approach is a stepping stone. Future work will explore ServiceWorker-like handlers that resolve protocols directly within the extension. See ipfs/in-web-browsers#212.
Thanks
Thanks to the Igalia team for their continued effort on this. Good progress is being made toward improving how browsers handle non-HTTP URIs.