IPFS Companion

Upgrade your browser with IPFS super powers

Firefox / Firefox for Android	Chrome / Brave / Opera / Edge

Lead Maintainer

Marcin Rataj

Table of Contents

• Background
• Features
• Install
• Contribute
• Troubleshooting
• Privacy Policy
• License

Background

This add-on enables everyone to access IPFS resources the way they were meant: from locally running IPFS node :-)

IPFS is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Learn more at ipfs.io (it is really cool, we promise!)

Features

Automagical Detection of IPFS Resources

IPFS Path in URL

Requests for IPFS-like paths (/ipfs/{cid} or /ipns/{peerid_or_host-with-dnslink}) are detected on any website.
If tested path is a valid IPFS address it gets redirected and loaded from a local gateway, e.g:

https://ipfs.io/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
→ http://127.0.0.1:8080/ipfs/QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR

DNSLink

Companion will detect presence of DNSLink in DNS records of visited websites and redirect HTTP request to a local gateway.

http://docs.ipfs.io
→ http://127.0.0.1:8080/ipns/docs.ipfs.io

This means if you visit websites with a valid DNSLink (eg. https://docs.ipfs.io, https://ipld.io, http://tr.wikipedia-on-ipfs.org) browser will load them from IPFS.

More details: DNSLink Support in IPFS Companion

X-Ipfs-Path

Companion will upgrade transport to IPFS if the header is found in any HTTP response headers. This is a fallback for edge cases when IPFS path is not present in URL.

More details: x-ipfs-path Header Support in IPFS Companion

Redirect Opt-Out

It is possible to opt-out from Gateway redirect by:

• a) suspending redirect via global toggle (see Disable All Redirects below)
• b) suspending redirect for via per website opt-out (in Active Tab section of Browser Action or Preferences)
• c) including x-ipfs-companion-no-redirect in the URL (as a hash or query parameter).

Quick Toggles

The Browser Action pop-up provides handy toggles for often used operations.

Disable Gateway Redirect Per Website

Active Tab actions include option to opt-out current website from Gateway redirect of any IPFS subresources.
Disabling redirect for DNSLink website will restore original URL as well:

Disable All Redirects

A handy toggle to disable all gateway redirects while keeping all other features enabled:

Suspend IPFS Extension

The "power" icon can be used to temporarily suspend all IPFS integrations (redirects, API status, content scripts, protocol handlers etc). Useful during testing. Extension can be re-enabled with a single click:

IPFS Status and Context Actions

• IPFS API and Gateway status
• Add local (quick import) or remote files (context menu) to IPFS with option to preserve filename
• Easy access to WebUI and add-on Preferences
• Toggle redirection to local gateway (automatic by default, manual mode can be enabled in Preferences)
• Additional actions for pages loaded from IPFS
  • Pin/Unpin of IPFS resources (via API)
  • Copy canonical IPFS address
  • Copy shareable URL to resource at preferred public gateway

Experiments!

(some are disabled by default, use Preferences screen to enable)

• Requests made via experimental protocols are re-routed to HTTP gateway (public or custom):
  • ipfs://$cid
  • ipns://$cid_or_fqdn
  • dweb:/ipfs/$cid
  • dweb:/ipns/$cid_or_fqdn
• Make plaintext IPFS links clickable (demo)
• Switch between External HTTP API and Embedded js-ipfs node. Read about differences at docs/node-types.

  

Install

Release Channel

We recommend installing the stable release via your browser's add-on store.

Firefox / Firefox for Android	Chrome / Brave / Opera / Edge

Note: ipfs-companion is designed to retrieve content from a locally running IPFS daemon.
Make sure IPFS is installed on your computer.

Beta Channel

Developers and enthusiasts can opt-in for Beta-quality channel with hand-picked Dev Builds:

• Beta for Firefox: Self-hosted Signed Dev Build
• Beta for Chromium-based browsers: Dev Build at Chrome Web Store

It is also possible to grab the last successful build from master, but these builds are not signed nor will automatically update: .zip bundles are meant only to be manually loaded via chrome://extensions (Chromium-based) or about:debugging (Firefox) for the purpose of quick smoke-testing.

Development

To work on the extension you need to install it from source rather than from the add on store.

1. Clone https://github.com/ipfs-shipyard/ipfs-companion.git
2. Run all-in-one dev build:

   $ npm run dev-build

3. Switch add-on/manifest.json to the browser of your choice:

   $ npm run bundle:firefox # for Firefox (build default)
   OR
   $ npm run bundle:chromium # for Chromium-based browsers

4. Load it into browser:

   • Chromium-based

     1. Enter chrome://extensions in the URL bar
     2. Enable "Developer mode"
     3. Click "Load unpacked extension..."
     4. Pick the directory add-on

   • Firefox

     1. Enter about:debugging in the URL bar
     2. Check "Enable add-on debugging"
     3. Click "Load Temporary Add-on"
     4. Pick the file add-on/manifest.json

See DEVELOPER-NOTES.md for more detailed instructions

Reproducible Build in Docker

Want to ensure prebuilt bundle does not include any additional code?
Don't want to install JS dependencies such as NodeJS and yarn?

Do an isolated build inside of Docker!

Run the following command for ending up with a built extension inside the build/ directory:

npm run release-build

It is an alias for running ci:build script inside of immutable Docker image, which guarantees the same output on all platforms.

Legacy Firefox (< 53) and XUL-Compatible Browsers

Legacy versions 1.x.x were based on currently deprecated Add-On SDK (Firefox-only).
While it is not maintained anymore, one can inspect, build and install it using codebase from legacy-sdk branch.
For historical background on the rewrite see Issue #20: Move to WebExtensions.

Contribute

Feel free to join in. All welcome. Open an issue!

If you want to help in developing this extension, please see CONTRIBUTING page ✨

The browser extension team hangs out at the #ipfs-in-web-browsers channel on Freenode.

This repository falls under the IPFS Code of Conduct.

TROUBLESHOOTING

The best place to ask your questions about IPFS in general, how it works and what you can do with it is at discuss.ipfs.io.
We are also available at the #ipfs channel, where most of IPFS community hangs out.

Questions specific to this browser companion can be asked directly at #ipfs-in-web-browsers

Import via Right-Click Does Not Work in Firefox

See this workaround.

Workaround for HTTP Redirect to Work with Ghostery

Ghostery is known to toy with HTTP-to-HTTPS redirect, which in some setups breaks websites utilizing public gateways. More details in #466. Until it is fixed upstream, a workaround is to whitelist affected site.

Rule to Work with NoScript with ABE Enabled

By default NoScript breaks this addon by blocking assets loaded from IPFS Gateway running on localhost.
To make it work, one needs to extend the SYSTEM Rulset and prepend it with IPFS whitelist:

# Enable IPFS redirect to LOCAL
Site ^http://127.0.0.1:8080/(ipfs|ipns)*
Anonymize

# Prevent Internet sites from requesting LAN resources.
Site LOCAL
Accept from LOCAL
Deny

Feel free to modify it, but get familiar with ABE rule syntax first.

Privacy Policy

See PRIVACY-POLICY.md

License

IPFS logo belongs to The IPFS Project and is licensed under a CC-BY-SA 3.0.

is-ipfs, js-multihash and other NPM dependencies are under MIT license, unless stated otherwise.

The add-on itself is released under CC0: to the extent possible under law, the author has waived all copyright and related or neighboring rights to this work, effectively placing it in the public domain.