{"id":13711243,"url":"https://github.com/ethersphere/swarm-extension","last_synced_at":"2025-05-03T19:31:01.407Z","repository":{"id":37004546,"uuid":"341994974","full_name":"ethersphere/swarm-extension","owner":"ethersphere","description":"PoC for Swarm Browser Extension","archived":false,"fork":false,"pushed_at":"2023-02-17T15:08:20.000Z","size":3939,"stargazers_count":14,"open_issues_count":47,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-07T20:21:23.330Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethersphere.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2021-02-24T18:23:43.000Z","updated_at":"2023-08-12T21:44:13.000Z","dependencies_parsed_at":"2023-01-17T13:01:58.972Z","dependency_job_id":null,"html_url":"https://github.com/ethersphere/swarm-extension","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethersphere%2Fswarm-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethersphere","download_url":"https://codeload.github.com/ethersphere/swarm-extension/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252241958,"owners_count":21717077,"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":[],"created_at":"2024-08-02T23:01:06.134Z","updated_at":"2025-05-03T19:31:00.575Z","avatar_url":"https://github.com/ethersphere.png","language":"TypeScript","funding_links":[],"categories":["Projects"],"sub_categories":["Tools"],"readme":"# Swarm Extension\n\n**Warning: This project has Proof of Concept state now. There will be breaking changes continuously in the future. Also, no guarantees can be made about its stability, efficiency, and security at this stage. It only provides a platform currently to show workarounds and examples for the current problems in dApp environments top on Swarm**\n\n\n**Info: For manifest v3 version of the extension, dApps should interact with the extension using the `Swarm Extension Library`. Check how it works [here](library/README.md).**\n\nThis browser extension provides an alternative to have a web3 environment in a web2 browser for users and dApps.\n\nUsers can interact with the Swarm network in two ways: by running their own Bee client or using a gateway solution.\nEither of the cases, users can set the connection data of the desired Bee client within the extension in order to channel all Bee client request to that trusted endpoint.\nOther settings can be placed regarding how the user wants to interact with the web3 applications, like using one selected postage batch for any file upload attempt of dApps.\n\nIn a web3 architecture the browser is the new server-side backend, therefore frontend applications (dApps) should communicate with it.\nFor that, there is a pre-defined [API](#fake-url) that dApps can request to and interact with the Bee client of the user in a secure and abstracted manner.\nBy that, there is no need to assume the user runs a Bee node on the default ports on their computer, or to fallback to a well-known public-gateway when referencing external Swarm resources; just refer to the representative, fixed and abstracted Bee client endpoints that the extension defines [in HTML](#Swarm-HTML) or [in JavaScript](#Custom-Protocol).\nThe web2 is based on domain-centric considerations, because of that, lot of features cannot be used in a secure way when many applications are loaded from the same (Bee) host.\nThat is way the extension has its [own Security Context](#dApp-origin-instead-of-host-based-origin) and separates dApps by their root content addresses.\nWith new Security Context, new governor mechanisms can emerge like [cross-domain localstorage handling](#Cross-Domain-Local-Storage).\n\n## Installation\n\nThe extension can be installed to Chromium based browsers currently, but we plan it to have on Firefox later as well.\n\nYou can build the project by running\n```sh\nnpm ci\nnpm run compile\n```\n\ncommands. If everything went right, then a `dist` folder appeared in the root of the project folder. That folder has to be [added to your browser extensions](chrome://extensions/) as an unpacked extension. You can load unpacked extensions only if you checked in the `Developer mode` (top-right corner).\n\n## Manifest V3 Changes\n\nSince manifest v2 extensions won't be allowed from June 2023, the Swarm Extension now supports manifest v3. But that brings some limitations, not present in v2. Here are the key changes in v3:\n\n- The `swarm` object won't be injected into dApp pages. Instead each dApp should include the [Swarm Extension Library](library/README.md) into its code to comunicate with the extension.\n- Blocking interceptors are not allowed in manifest v3, so the new implementation uses the [Declarative Network Request API](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/). This requirement prevents the extension from checking session ID for fake URL requests. That means the extension cannot check the security context of the links that are being accessed.\n- If bee URL is set to `localhost`, then fake URL links are redirected to subdomain based bee URLs. For example, trying to access the `bzz://site.eth` URL will result in accessing the `http://site.swarm.localhost:1633/` URL.\n\n\n## Fake URL\n\nThere is a need to separate dApp context from the user context in order to restrict dApp actions work with keys and resources of the user.\nIn a web3 environment the browser acts like a backend server. To accomplish this desired role it has to introduce endpoints that dApps can interact with.\nThese endpoints are called `Fake URLs`.\nThe naming came from these URLs should not point to any real existing endpoint that a common server could serve,\nso the host part of the URL (probably) is not the real destination.\n\nWeb applications can make requests to other decentralized application APIs in the scope of the user\nby aiming its corresponding Fake URLs that basically make redirect to these real API address.\nIt is neccessary, because the targeted services may need additional headers and keys to perform the action that **should not be handled on dApp side**.\nThe extension can keep these keys and configurations on the side of the user\nand it does not expose the secrets to the applications that initialize the call.\nIn this sense it also works like a `proxy`.\n\nThis architecture also allows changing the default URLs of decentralized services (Bee) to any arbitrary one,\nmeanwhile dApps do not have to guess this address.\nFor example Bee client has default `http://127.0.0.1:1633`, user can change it to any other port or even other gateway host,\nthe dApps will call it in the same way.\n\n### Callable Endpoints\n\nFor any action the Fake URL host is `http://swarm.fakeurl.localhost`.\nAs it is written earlier, it is not the address of the Bee client,\nit is just a reserved host address that the extension took and built its Fake URL paths on it.\nIf the user changes their Bee API address, these endpoints still remain the same from dApp side.\n\n- `http://swarm.fakeurl.localhost/bzz/*` - `BZZ protocol` redirects to this fake URL, thereby in `*` can be not only content reference with its path, but any BZZ protocol compatible reference. It will be redirected to `bzz` endpoint of the Bee client.\n- `http://swarm.fakeurl.localhost/bee-api/*` - it will be forwarded to the Bee API. `*` has to be valid Bee API path\n\n## Custom Protocol\n\nThe Swarm protocol to address other P2P content is `bzz`. It makes a redirection to the BZZ endpoint of the Bee node.\nIf you type `bzz://{content-address}` into the address bar, the page will be redirected to `http(s)://{your-bzz-node-host}/bzz/{content-address}`. This requires the default search engine of the browser to be set to Google.\nIt also behaves the same on simple google searches on `https://google.com`.\n\nThere will be need for other Swarm specific protocols (or extend the current one), which handle different type of feeds and mutable content.\n\nYou can read about it in more detail in the following section\n\n### Swarm HTML\n\nYou can refer to any `bzz` resource in html if you add attribute `is=swarm-X` to your html element, where `X` is the name of the HTML tag element, such as `\u003cimg is=\"swarm-img\" src=\"https://{cid-or-ens-name}.bzz.link\" /\u003e`.\n\nCurrent supported elements:\n* `a` -\u003e `\u003ca is=\"swarm-a\" (...)`\n* `img` -\u003e `\u003cimg is=\"swarm-img\" (...)`\n* `video` -\u003e `\u003cvideo is=\"swarm-video\" (...)`\n* `source` -\u003e `\u003caudio controls\u003e\u003csource is=\"swarm-source\" (...)`\n* `iframe` -\u003e `\u003ciframe is=\"swarm-iframe\" (...)`\n\nat references, you can use the `bzz` protocol or the `bzz.link` structure that is detailed below.\n\n## CID references and Public Gateway replacement\n\nSwarm has service to get content from its network through public gateways, and you can refer any Swarm content by CIDs or by their ENS names without `.eth` ending in form of `https://{cid}.bzz.link/{path}` or `https://{ens-name}.bzz.link` respectively.\nThese requests can be tunneled to the configured Bee client of the user instead of using gateways.\n\nWith this feature, dApps can satisfy simultaniously gateway users and others who locally run their bee node.\nAll requests towards the `bzz.link` gateways will be cancelled and tunneled to the local Bee client in case of extension users.\n\nThe consequence of this behaviour the dApps which use external bzz.link references in their HTML code and want to available via both bzz.link gateways and private extension connections have to use [Swarm HTML elements](#Swarm-HTML).\n\n## dApp origin instead of host-based origin\n\nAll Swarm content that the extension renders, without using subdomain, will be put into _sandbox_ mode even in root level by _Content Security Policy_ headers.\nIt means dApps will act like a different, distinct webpage from the Bee host that serves those.\nTherefore no traditional _cookies_ or _localStorage_ is available for dApps, but equivalent services of those are.\n\nIn order to substitue these traditional stateful behaviours of the applications with something else, the Swarm Extension introduces\nthe `dApp Security Context` as a new abstraction of origins.\n\n### Cross-Domain Local Storage\n\nIn Web3, several different and distinct webpages can be rendered under one particular P2P client host.\nIt is a problem, because if the user changes its P2P client host then they have to rebuild again the dApp state from the start.\n\nThis unintended behaviour can be sorted out by the `dApp Security Context` of the extension:\nthe handling of `localStorage` method happens based on the `sessionId` of the dApp.\n\nThereby even if the user changes its P2P client host, the state and their session will remain - unlike using only subdomain content address URLs with the traditional `localStorage`.\n\nOf course, it is not necessary to set any ID manually, just call the usual `localStorage` methods but under the `swarm` object, created as an instance of the [Swarm Class](library/README.md#swarm-class):\ninstead of `window.localStorage.setItem('swarm', 'bzz')` you can call `swarm.localStorage.setItem('swarm', 'bzz')` in order to persist data in the browser.\n\nThe `setItem` and `getItem` methods here are `async` methods, so these return with `Promise`.\n\n## Contribution\n\nPRs and any new ideas are welcome!\n\nThere is a hot-reload functionality of extension compilation to react on code changes.\n\n```sh\nnpm run dev\n```\n\nif you run [test in demo mode](#Test), the extension in the Chromium browser will be automatically reloaded.\n\n### Test\n\nThere are some illustrative tests which show how these PoC ideas work.\nFor running tests, you need to run a Bee node.\nBy default, tests are run against `http://127.0.0.1:1633`. You can change it by setting environment variable `BEE_API_URL`.\nOn test pages, if a Jinn can show up under a section which means it works as it is intended to be.\nOn other hand, if Jafar comes into the picture, than it points out a bad/insecure use-case.\n\nFor tests, execute the following:\n\n```bash\n $ npm run compile \u0026\u0026 npm run test\n```\nIn order to present or interact with functionalities of `swarm-extension`, run command\n```bash\n $ npm run compile \u0026\u0026 npm run test:demo\n```\nif everything went great, you can see the test pages in a Chromium browser.\n\nFor testing use Node version \u003e= 14!\n\nIf you have timeout problems, you can always raise the global timeout limit (in milliseconds) by passing `--testTimeout=60000` for the test.\n\nIn case of many subsequent test runs, set `BEE_STAMP` with a valid postage stamp in order to not wait for stamp generation.\n\n### BZZ protocol test\n\nFor BZZ protocol, there are test pages to illustrate the functionality.\nThe test page folder is located in [test/bzz-test-page](test/bzz-test-page).\nIn its [index page](test/bzz-test-page/index.html), you see how you can refer to external Swarm content in HTML files without assuming any gateway host.\n\n### Maintainers\n\n- [nugaon](https://github.com/nugaon)\n- [Cafe137](https://github.com/Cafe137)\n- [tomicvladan](https://github.com/tomicvladan)\n\nSee what \"Maintainer\" means [here](https://github.com/ethersphere/repo-maintainer).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethersphere%2Fswarm-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethersphere%2Fswarm-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethersphere%2Fswarm-extension/lists"}