_                           _          _ 
            | |                         | |        | |
 _   _ _ __ | |__   ___  _   _ _ __   __| | ___  __| |
| | | | '_ \| '_ \ / _ \| | | | '_ \ / _` |/ _ \/ _` |
| |_| | | | | |_) | (_) | |_| | | | | (_| |  __/ (_| |
 \__,_|_| |_|_.__/ \___/ \__,_|_| |_|\__,_|\___|\__,_|

• What is Unbounded?
• Features
• Related work
• System components
• Quickstart for devs
• Observing networks with netstate
• UI

Unbounded is a next-gen technology stack for circumventing internet censorship using browser-based P2P proxies. It organizes an ephemeral swarm of short-lived residential IP addresses, provided by volunteers in less censored regions, which create censorship resistant routes for network requests originating from users in heavily censored regions.

Here are just a few of the things you can do:

• Turn your friends into a private swarm to unblock a loved one in a censored region (tutorial) 🔥
• Add a P2P transport to your circumvention app (tutorial coming soon)
• Volunteer on the Lantern network with just one click (link)
• Add the Lantern volunteer widget to your website (tutorial coming soon)
• Deploy a permanent volunteer node on a Raspberry Pi (tutorial coming soon)

• End-to-end connection state persistence across ephemeral peer transports
• HTTP and SOCKS5 mode
• Concurrent client for IP efficiency: 1 volunteer can proxy for N users simultaneously
• N:M multiplexing
• High performance, low latency, rapid peer discovery
• Maintainable and debuggable: one cross-platform WebAssembly-friendly engine that runs everywhere

Unbounded is a descendant of the "flash proxy" concept first described in 2012 by David Fifield, Nate Hardison, Jonathan Ellithorpe, Emily Stark, Dan Boneh, Roger Dingledine, and Phil Porras (paper).

uProxy is a historical project exploring similar ideas that also started in 2012 as a collaboration between Google Ideas (now Jigsaw), the University of Washington, and the Brave New Software Project, the creators of Lantern.

Snowflake, part of the Tor project, is an evolution of the same concenpt, with roots in both flash proxy and uProxy, and it is widely used today.

The idea to create connection state persistence across ephemeral peer transports was formalized by David Fifield as "Turbo Tunnel" in 2020 (paper).

1. Clone this repo.

2. Configure Mozilla Firefox to use a local HTTP proxy. In settings, search "proxy". Select Manual proxy configuration. Enter address 127.0.0.1, port 1080, and check the box labeled Also use this proxy for HTTPS.

3. Build the native binary desktop client: cd cmd && ./build.sh desktop

4. Build the native binary widget: cd cmd && ./build.sh widget

5. Build the browser widget: cd cmd && ./build_web.sh

6. Start Freddie: cd freddie/cmd && PORT=9000 go run main.go

7. Start the egress server: cd egress/cmd && PORT=8000 go run egress.go

8. Start a desktop client: cd cmd/dist/bin && FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./desktop

9. Decision point: do you want to run a native binary widget or a browser widget? To start a native binary widget: cd cmd/dist/bin && FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./widget. Alternatively, to start a browser widget, follow the UI quickstart.

The widget and desktop client find each other via the discovery server, execute a signaling step, and establish several WebRTC connections.

10. Start Mozilla Firefox. Use the browser as you normally would, visiting all your favorite websites. Your traffic is proxied in a chain: Firefox -> local HTTP proxy -> desktop client -> webRTC -> widget -> WebSocket -> egress server -> remote HTTP proxy -> the internet.

The netstate module is a work-in-progress tool for observing Unbounded networks. netstate currently visualizes network topology, labeling each Unbounded node with an arbitrary, user-defined "tag" which may be injected at runtime.

netstated is a distributed state machine which collects and processes state changes from Unbounded clients. It serves a network visualization at GET /. The gv visualizer client looks for a netstated instance at localhost:8080.

In the example below, we assume that Freddie is at http://localhost:9000 and the egress server is at http://localhost:8000:

1. Start netstated: cd netstate/d && go run netstated.go

2. Start a widget as user Alice: cd cmd/dist/bin && NETSTATED=http://localhost:8080/exec TAG=Alice FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./widget

3. Start a desktop client as user Bob: cd cmd/dist/bin && NETSTATED=http://localhost:8080/exec TAG=Bob FREDDIE=http://localhost:9000 EGRESS=http://localhost:8000 ./desktop

4. Open a web browser and navigate to http://localhost:8080. As Alice and Bob complete the signaling process and establish connection(s) to one another, you should see the network you have created. You must refresh the page to update the visualization.

The UI is bootstrapped with Create React App. Then "re-wired" to build one single js bundle entry using rewire. The React app will bind to a custom <browsers-unbounded> DOM el and render based on settings passed to the dataset. In development, this html can be found in ui/public/index.html. In production, the html is supplied by the "embedder" via https://unbounded.lantern.io/embed.

Example production embed:

<browsers-unbounded
   data-layout="banner"
   data-theme="dark"
   data-globe="true"
   data-exit="true"
   style='width: 100%;'
></browsers-unbounded>
<script defer="defer" src="https://embed.lantern.io/static/js/main.js"></script>

This tables lists all the available settings that can be passed to the <browsers-unbounded> DOM el via the data-* attributes. The "default" column shows the default value if the attribute is not set.

In development, these settings can be customized using the REACT_APP_* environment variables in the .env or in your terminal. For example, to run the widget in "panel" layout, you can run REACT_APP_LAYOUT=panel yarn start. To run the widget with mock data, you can run REACT_APP_MOCK=true yarn start.

Settings can also be passed to the widget via the data-* attributes in ui/public/index.html. For example, to run the widget in "panel" layout, you can set data-layout="panel" in ui/public/index.html.

If you enable the editor (by setting REACT_APP_EDITOR=true or data-editor="true"), you can also edit the settings dynamically in the browser using a UI editor the renders above the widget. Note that the mock and target settings are not dynamic and therefore not editable in the browser. These two settings are static and must be set at the time the wasm interface is initialized.

Links:

Github pages sandbox

Unbounded website

1. Work from the ui dir: cd ui
2. Install deps: yarn

Development:

1. Copy the example env: cp .env.development.example .env.development
2. Start the dev server: yarn dev:web and open http://localhost:3000 to view it in the browser.

Production: you don't deploy by hand. Merging to main publishes both widget.wasm and the page bundle to the gh-pages branch (and from there to embed.lantern.io) via .github/workflows/build-widget-wasm.yml, gated on the js/wasm build and the Go unit tests. That covers unbounded.lantern.io and every third-party embedder at once, since they all load https://embed.lantern.io/static/js/main.js by absolute URL.

Before pushing UI changes, build the way CI does:

CI=true yarn build:web

react-scripts turns ESLint warnings into errors when CI is set, and GitHub Actions sets it automatically — so a plain yarn build:web can print warnings, succeed locally, and still fail the publish. Note the failure is safe: the publish job verifies the build before it touches gh-pages, so a broken build stops rather than shipping.

1. Work from the ui dir: cd ui

2. Configure your .env file: cp .env.development.example .env.development

   1. Set REACT_APP_WIDGET_WASM_URL to your intended hosted widget.wasm file. If you are serving it from client in step #8, use http://localhost:9000/widget.wasm. If you ran ./build_web.sh (step #7) you can also use /widget.wasm. To config for prod point to a publicly hosted widget.wasm e.g. https://embed.lantern.io/widget.wasm. If you know you know, if not, you likely want to use /widget.wasm.
   2. Set REACT_APP_GEO_LOOKUP_URL to your intended geo lookup service. Most likely https://geo.getiantem.org/lookup or http://localhost:<PORT>/lookup if testing geo lookups locally
   3. Set REACT_APP_STORAGE_URL to your intended iframe html for local storage of widget state and analytics. Most likely https://embed.lantern.io/storage.html or /storage.html if testing locally
   4. Set any REACT_APP_* variables as needed for your development environment. See UI settings and configuration for more info.
   5. Configure the WASM client endpoints: REACT_APP_DISCOVERY_SRV, REACT_APP_DISCOVERY_ENDPOINT, REACT_APP_EGRESS_ADDR & REACT_APP_EGRESS_ENDPOINT
   6. Configure the CMS and translations: STRAPI_API_TOKEN & STRAPI_API_URL

3. Install the dependencies: yarn

4. To start in developer mode with hot-refresh server (degraded performance): run yarn dev:web and visit http://localhost:3000

5. To build optimized for best performance:

   1. First configure your .env file: cp .env.production.example .env.production (see Step 2)
   2. Run yarn build:web

6. To serve a build:

   1. Install a simple server e.g. npm install -g serve (or your lightweight http server of choice)
   2. Serve the build dir e.g. cd build && serve -s -l 3000 and visit http://localhost:3000

7. To deploy to GitHub Pages: nothing to do — merging to main publishes. See the warning under UI quickstart for devs before reaching for yarn deploy, which regresses the published widget.wasm.

8. Coming soon to a repo near you: yarn test

1. Work from the ui dir: cd ui

2. Install the dependencies: yarn

3. Configure your .env file: cd extension && cp .env.example .env

   1. Set EXTENSION_POPUP_URL to your intended hosted popup page. If you are serving it from ui in step #6, use http://localhost:3000/popup. To use prod, set to https://embed.lantern.io/popup.
   2. Set EXTENSION_OFFSCREEN_URL to your intended hosted offscreen page. If you are serving it from ui in step #6, use http://localhost:3000/offscreen. To use prod, set to https://embed.lantern.io/offscreen.

4. To start in developer mode with hot-refresh server:

yarn dev:ext chrome
yarn dev:ext firefox 

This will compile the extension and output to the ui/extension/dist dir. You can then load the unpacked extension in your browser of choice.

• For Chrome, go to chrome://extensions and click "Load unpacked" and select the ui/extension/dist/chrome dir.
• For Firefox, go to about:debugging#/runtime/this-firefox and click "Load Temporary Add-on" and select the ui/extension/dist/firefox/manifest.json file.
• For Edge, go to edge://extensions and click "Load unpacked" and select the ui/extension/dist/edge dir.

4. To build for production:

yarn build:ext chrome
yarn build:ext firefox 

This will compile the extension and output a compressed build to the ui/extension/packages dir.

The copy and translations are bootstrapped with Strapi as a headless CMS to manage translations and other content for the UI.

The translations are queried at build time and the UI uses the i18next library to manage the translations and the react-i18next library to bind the translations to the UI components.

To re-query the translations from the CMS, run yarn translate. This will fetch the latest translations from the CMS and update the src/translations.json file.