relaycorp / awala-gateway-desktop

Awala Gateway for Desktop

Awala Gateway for Desktop

The Awala Gateway for Desktop is a private gateway for Windows 8+ and Linux desktops, with experimental support for macOS. The installers can be found in the latest GitHub release.

This repository contains the source code for the app, which is also a reference implementation of a private gateway in the Awala protocol suite.

This document is aimed at advanced users and (prospective) contributors. We aim to make the app as simple and intuitive as possible, and we're therefore not planning on publishing end-user documentation at this point. To learn more about using Awala, visit awala.network/users.

Awala bindings

This private gateway implements Awala bindings as follows:

• Local endpoints communicate with the private gateway via a PoWeb server on 127.0.0.1:13276. This server is implemented with the PoWeb binding, and the Fastify and ws servers.
• When the Internet is available and the Internet gateway is reachable, this private gateway will communicate with its public counterpart using Relaycorp's PoWeb client.
• When communicating with couriers over WiFi, this private gateway uses the CogRPC binding through Relaycorp's CogRPC client.

The local communication with endpoints does not use TLS, but all other connections are external and therefore require TLS.

By default, instances of this gateway are paired to Relaycorp's Frankfurt gateway.

Security and privacy considerations

The items below summarize the security and privacy considerations specific to this app. For a more general overview of the security considerations in Awala, please refer to RS-019.

No encryption at rest

This app does not (currently) support encryption at rest, so a malicious app on your computer could get hold of the private keys used by this gateway. Users are highly encouraged to use full-disk encryption to protect such keys in the event that the device were lost or stolen.

Note that because Awala employs end-to-end encryption, compromising these keys won't compromise the encryption of the messages exchanged by your Awala-compatible apps. The keys of any private gateway are used to sign messages and issue Awala PKI certificates, and to encrypt/decrypt cargo exchanged with its Internet gateway.

External communication

In addition to communicating with its Internet gateway, this app communicates with the following:

• https://cloudflare-dns.com/dns-query as the DNS-over-HTTPS (DoH) resolver. DoH is only used to resolve SRV records for the Internet gateway (e.g., _awala-gsc._tcp.frankfurt.relaycorp.cloud), as we delegate the DNSSEC validation to the DoH resolver.
• The host running the DHCP server on port 21473, when the device is connected to a WiFi network but disconnected from the Internet. We do this to check whether the device is connected to the WiFi hotspot of a courier.
• Other apps on the same device can potentially communicate with the local PoWeb server provided by this app on 127.0.0.1:13276. Because this server uses the HTTP and WebSocket protocols, we block web browser requests by disabling CORS and refusing WebSocket connections with the Origin header (per the PoWeb specification).

This app doesn't track usage (for example, using Google Analytics), nor does it use ads.

App signing

The Windows installer is signed with a certificate issued to Relaycorp, Inc..

Naming rationale

We're referring to this app as "Awala" in the user interface, even though this is obviously one of the components that make up the network, in order to hide technical details from the end user. The terms "private gateway" or "gateway" may be more accurate, but we don't think they sound user-friendly.

However, we do use the terms "private gateway" or "gateway" in the code base because we absolutely need accuracy there.

Development

System dependencies

You only need Node.js 16+ installed.

Setup

npm install
npm run bootstrap

Code structure

This is a monorepo and all components can be found under packages.

Contributing

We love contributions! If you haven't contributed to a Relaycorp project before, please take a minute to read our guidelines first.

awala-gateway-desktop's Issues

Implement cargo delivery

Using relaycorp/relaynet-cogrpc-js#14

The cargo must be delivered after the relayer has produced a valid Cargo Collection Authorization.

Optionally use Pluggable Transports

See equivalent issue in Android gateway project: relaycorp/relaynet-gateway-android#14

Release job isn't triggered when semantic-release creates a release

Because semantic-release uses a GH_TOKEN, not a PAT.

I should just merge the release job into the CI job, which is more complicated than I would've liked.

Build Windows installer

Using https://github.com/electron/windows-installer

Implement import from disk

So we can import cargo from a USB flash drive, for example.

GitHub release should only be created when all installers are available

Right now, we're creating the release and then attaching the installers as they become available.

This is problematic because there's a (brief) period of time during which all/some installers will be missing.

Implement connection to relayer

There's two parts to this: Write a script to trigger the connection and the actual initialisation of the connection in the gateway.

It should use a signal or some other IPC method to tell the gateway to connect to the relayer.

This script could be extended in the future to output the logs of the relay if we find that makes sense.

Implement quitting from CRC

Using relaycorp/relaynet-cogrpc-js#10

Electron's icon is used instead of Awala's on Windows

Publish app on Microsoft Store

See:

• https://www.electron.build/configuration/appx
• https://www.advancedinstaller.com/msix-publish-microsoft-store.html
• Resume: https://partner.microsoft.com/en-US/dashboard/Account/CertificateUpload

See also #188

Save logs to files instead of stdout/stderr

Because the daemon crashes when forked by the UI: stdout/stderr can't be used. See also #155.

See example in https://github.com/relaycorp/awala-gateway-desktop/compare/package-debugging

App takes up too much disk space

As of this writing, the installer takes up 237 MiB and the app installed takes up 1.3 GiB.

Set up development environment

• Configure linter.
• Configure build automation.
• Configure test runner.
• Configure CIS.
• Etc.

Implement and integrate PoWebSocket server

Using the stream from https://github.com/relaycorp/relaynet-powebsocket-js.

Amongst other things, this will also involve using the core library to parse and validate parcels.

Proof of concept

This will be the equivalent to implementing PoWebSocket/gateway.js and then integrating it as it was done in user-gateway (note how powebsocketGateway is used).

Implement parcel delivery

See: https://github.com/relaynet/poc/blob/master/PoWebSocket/gateway.js

Connection with courier isn't detected if app started offline

Make `lerna bootstrap` work again

I had to disable it in #185 because it was breaking CI.

Native dependencies don't work in Electron

The native dependencies in the daemon package (i.e., gRPC and SQLite) aren't working. I can build the app, but the daemon errors out when forked:

/home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/grpc_extension.js:55
    throw error;
    ^

Error: Failed to load gRPC binary module because it was not installed for the current system
Expected directory: electron-v12.0-linux-x64-glibc
Found: [node-v72-linux-x64-glibc]
This problem can often be fixed by running "npm rebuild" on the current system
Original error: Cannot find module '/home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/node/extension_binary/electron-v12.0-linux-x64-glibc/grpc_node.node'
Require stack:
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/grpc_extension.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/client_interceptors.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/client.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/index.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/@relaycorp/cogrpc/build/main/lib/client.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/@relaycorp/cogrpc/build/main/index.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/build/sync/courierSync/CourierSync.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/build/sync/StatusMonitor.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/build/server/control/connectionStatus.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/build/server/index.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/build/daemon.js
- /home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/build/bin/gateway-daemon.js
    at Object.<anonymous> (/home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/grpc_extension.js:53:17)
    at Module._compile (internal/modules/cjs/loader.js:1078:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1108:10)
    at Module.load (internal/modules/cjs/loader.js:935:32)
    at Module._load (internal/modules/cjs/loader.js:776:14)
    at Function.f._load (electron/js2c/asar_bundle.js:5:12684)
    at Module.require (internal/modules/cjs/loader.js:959:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at Object.<anonymous> (/home/gus/repos/awala-gateway-desktop/packages/ui/app/daemon/node_modules/grpc/src/client_interceptors.js:144:12)
    at Module._compile (internal/modules/cjs/loader.js:1078:30) {
  code: 'MODULE_NOT_FOUND'
}
(node:26471) UnhandledPromiseRejectionWarning: ReferenceError: WebSocket is not defined
    at updateToolTip (webpack://ui/./src/electron/main.ts?:93:39)
    at processTicksAndRejections (internal/process/task_queues.js:93:5)

I've tried the following but hadn't managed to make things work (I'm sure I'm doing something wrong but can't tell what it is):

• https://www.npmjs.com/package/grpc#about-electron
• https://www.electronjs.org/docs/tutorial/using-native-node-modules#installing-modules-and-rebuilding-for-electron

See #90, for example.

Can you please look into this when you get a chance, Lilia?

Implement signing of endpoint certificates

Per Relaynet Core (internal PDC requirements).

Pressing cancel button in courier sync screen doesn't actually cancel it

It seems like the client isn't closing the WebSocket connection.

Electron app doesn't crash when daemon fails to be forked

#91 didn't cause the app to crash.

This issue may become irrelevant depending on the solution to #91.

Add support for macOS

It's likely that the app can be ported to macOS with minimal tweaks, since we're using Electron.

The main thing blocking this is that we need to purchase a macOS device. Even if an external contributor volunteers to do this work, I still wouldn't approve the PR for two reasons:

• We'd still need to test it to ensure the quality of the integration is adequate.
• Going forward, as the app evolves, we'd need to ensure it continues to work well on macOS. We can't fully rely on the functional test suite, because we also have to test a client-server connection over WiFi.

Implement parcel collection

AppImage does not start when run from KDE's file browser (Dolphin)

See: https://discourse.appimage.org/t/appimage-can-only-be-run-from-terminal-on-kde/2341

This won't matter once we release the Snap instead (#188).

Sync with courier breaks due to Electron bug

#865 introduced a dependency on the AES-KW cipher but Electron doesn't support it, so the gateway can't encrypt or decrypt cargo.

See: relaycorp/relaynet-core-js#367

Implement UI using Electron

A screen for each journey:

• Pair with relaying gateway.
• Sync with relayer.

UI doesn't show correct version

It's always 1.0.0:

Daemon reports DISCONNECTED state when it should be UNREGISTERED

I must've introduced a regression.

Screen to migrate public gateway doesn't default to current gateway

It defaults to example.relaycorp.cloud.

Implement export to disk

So we can save cargo to USB flash drives.

A valid CCA must be provided first.

See also #16.

Integrate CoSocket client

Using https://github.com/relaycorp/relaynet-cosocket-js/.

Amongst other things, this will also involve using the core library to parse and validate cargo.

Proof of concept

The relay script in the PoC illustrates how the CoSocket client can be integrated (notice how CoSocketClient is used).

Courier sync is reported as successful even when it fails

For example, whilst checking why I'm not seeing the screen in the "UNREGISTERED" status, I started a sync with the courier.

I expected that sync to fail because we're in the UNREGISTERED status, but the UI immediately showed the screen you'd see when the sync succeeds. But I can see in the daemon logs that the request was aborted early on because of the current state:

{"level":40,"time":1619709970826,"pid":110247,"hostname":"relaybox","msg":"Aborting courier sync because gateway is unregistered"}

It should be possible to reproduce this by disconnecting from the courier's WiFi hotspot, but I haven't tried that.

Support reproducible builds

To protect ourselves and our users: https://reproducible-builds.org/

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Implement cargo collection

Using relaycorp/relaynet-cogrpc-js#15

Clicking 'Try again' after failed courier sync does nothing

PoWeb server: WS socket is suddenly closed after sending first parcel

And the close event isn't fired, so we can't handle it.

Since we'd be trying to write to a closed stream, that crashes the app with:

Error: WebSocket is not open: readyState 3 (CLOSED)
    at sendAfterClose (/home/gus/repos/awala-gateway-desktop/packages/ui/app/node_modules/daemon/node_modules/ws/lib/websocket.js:763:17)
    at WebSocket.send (/home/gus/repos/awala-gateway-desktop/packages/ui/app/node_modules/daemon/node_modules/ws/lib/websocket.js:345:7)
    at Duplex.duplex._write (/home/gus/repos/awala-gateway-desktop/packages/ui/app/node_modules/daemon/node_modules/ws/lib/stream.js:169:8)
    at writeOrBuffer (internal/streams/writable.js:358:12)
    at Duplex.Writable.write (internal/streams/writable.js:303:10)
    at Object.sink (/home/gus/repos/awala-gateway-desktop/packages/ui/app/node_modules/daemon/node_modules/stream-to-it/sink.js:71:20)

I can reproduce this reliably by running the ping command twice (awala-ping ping).

Implement new home screen for "UNREGISTERED" state

https://www.figma.com/file/M6DfwuKiwpab5NCcuT28bC/Gateway-Desktop-App?node-id=446%3A3

https://github.com/relaycorp/awala-gateway-desktop/tree/master/packages/daemon/src/server/control#sync-status-sync-status

Publish app on Snapcraft

I tried to do it with:

linux:
  target:
    - AppImage
    - snap
  category: Network
  icon: src/electron/assets/logo.png
snap:
  buildPackages:
    - libc6
  stagePackages:
    - default
    - libc6
    - libappindicator1

But got this runtime error:

$ awala
Gtk-Message: 12:29:47.619: Failed to load module "colorreload-gtk-module"
/snap/awala/x1/app/resources/app.asar/node_modules/daemon/node_modules/grpc/src/grpc_extension.js:58
    throw e;
    ^

Error: Failed to load /snap/awala/x1/app/resources/app.asar/node_modules/daemon/node_modules/grpc/src/node/extension_binary/electron-v12.0-linux-x64-glibc/grpc_node.node. /snap/awala/x1/lib/x86_64-linux-gnu/libm.so.6: version `GLIBC_2.29' not found (required by /run/user/1000/snap.awala/.org.chromium.Chromium.ywNXIS)
    at process.func [as dlopen] (electron/js2c/asar_bundle.js:5:1846)
    at Object.Module._extensions..node (internal/modules/cjs/loader.js:1138:18)
    at Object.func [as .node] (electron/js2c/asar_bundle.js:5:2073)
    at Module.load (internal/modules/cjs/loader.js:935:32)
    at Module._load (internal/modules/cjs/loader.js:776:14)
    at Function.f._load (electron/js2c/asar_bundle.js:5:12684)
    at Module.require (internal/modules/cjs/loader.js:959:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at Object.<anonymous> (/snap/awala/x1/app/resources/app.asar/node_modules/daemon/node_modules/grpc/src/grpc_extension.js:32:13)
    at Module._compile **(internal/modules/cjs/loader.js:1078:30)**

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

Cannot push to the Git repository.

semantic-release cannot push the version tag to the branch master on the remote Git repository with URL https://x-access-token:[secure]@github.com/relaycorp/awala-gateway-desktop.git.

This can be caused by:

• a misconfiguration of the repositoryUrl option
• the repository being unavailable
• or missing push permission for the user configured via the Git credentials on your CI environment

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Generate license report

Moving from Figma to Github. :)

I just came across https://www.npmjs.com/package/license-report so it seems like we could run it as part of the build process, and it'd give us a JSON document with all the data about the libraries we're using.

Write end-user documentation

• Install instructions.
• How to use.
• Etc.

Write up README

• Intro to prospective contributors.
• Etc.

Integrate native keychain to encrypt private key(s) at rest

Use https://www.electronjs.org/docs/latest/api/safe-storage

Set up Continuous Integration

Add animation to courier sync

Design: https://relaycorphq.slack.com/archives/C01Q1SXJP41/p1619360571004000

Courier sync hangs when there's no outgoing cargo

It hangs at the delivery stage.

It works absolutely fine if there's at least one outgoing cargo.

Implement collection of Parcel Delivery Deauthorization

Per Relaynet Core (internal PDC requirements).

Packaged app can't fork the daemon when asar is enabled

In a packaged electron app, the app directory is typically converted to an asar archive.

The problem is we currently need to cwd into the daemon directory to run the server. Since this is a virtual directory in an archive file, you can't. Possibly this could be resolved by making the daemon agnostic to the current working directory. Or we can try to exclude the daemon from the asar using electron-builder's config asarUnpack.

See electron/electron#2708