From d23264b86b2dbba44cd39c4729206973fcd51b0e Mon Sep 17 00:00:00 2001 From: Nadav Ivgi Date: Wed, 15 Aug 2018 21:05:23 +0000 Subject: [PATCH] Update docs and CLI help --- LICENSE | 4 + README.md | 300 +++++++++++++++-------------------------- doc/docker.md | 10 +- doc/onion.md | 30 +++++ doc/startup-systemd.md | 15 +++ doc/tls.md | 59 ++++++++ src/cli.js | 4 +- src/transport/tls.js | 2 +- 8 files changed, 225 insertions(+), 199 deletions(-) create mode 100644 doc/onion.md create mode 100644 doc/startup-systemd.md create mode 100644 doc/tls.md diff --git a/LICENSE b/LICENSE index 89de354..d7ea187 100644 --- a/LICENSE +++ b/LICENSE @@ -1,3 +1,7 @@ +The MIT License (MIT) + +Copyright 2018 Nadav Ivgi + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights diff --git a/README.md b/README.md index df5202b..d52e525 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,67 @@ # Spark Lightning Wallet -A minimalistic wallet GUI for [c-lightning](https://github.com/ElementsProject/lightning), -accessible over the web or through mobile and desktop apps. - [![npm release](https://img.shields.io/npm/v/spark-wallet.svg)](https://www.npmjs.com/package/spark-wallet) [![docker release](https://img.shields.io/docker/pulls/shesek/spark.svg)](https://hub.docker.com/r/shesek/spark) [![MIT license](https://img.shields.io/github/license/elementsproject/spark.svg)](https://github.com/elementsproject/spark/blob/master/LICENSE) [![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) -[![IRC](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)](https://webchat.freenode.net/?channels=c-lightning) +[![IRC](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)](https://webchat.freenode.net/?channels=spark-wallet) :zap: Simple & minimalistic :zap: Purely off-chain :zap: Near-zero configuration :zap: Progressive Web App -:zap: Cordova and Electron builds :zap: Personalizable themes -:zap: Automatic self-signed certs +:zap: Mobile and desktop apps +:zap: Automatic self-signed TLS :zap: LetsEncrypt integration :zap: Tor hidden service (v3) :zap: ------ +![Spark screenshot](https://user-images.githubusercontent.com/877904/44296418-74688a80-a2c7-11e8-8dba-08a017eceb11.png) + +## Contents + +- [Introduction](#introduction) +- [Server installation](#server-installation) (for web access) +- [Desktop apps](#desktop-apps) (for Linux, macOS and Windows) +- [Mobile app](#mobile-app) (for Android, iOS coming soon) +- [Progressive Web App](#progressive-web-app) +- [GUI controls](#gui-controls) +- [Browser support](#browser-support) +- [Developing](#developing) +- [Code signing & reproducible builds](#code-signing--reproducible-builds) +- [CLI options](#cli-options) + +## Introduction + +Spark is a minimalistic wallet GUI for c-lightning, accessible over the web or +through mobile and desktop apps (for Android, Linux, macOS and Windows). +It is currently aimed for technically oriented users and is not an all-in-one package, +but rather a "remote control" interface for a c-lightning node that has to be managed separately. + +Spark currently focuses on the core aspects of day-to-day usage: sending, receiving and viewing history. +Peers and channels are expected to be managed using the RPC for now. - -    - -    - -    - +Spark is a purely off-chain wallet, with no on-chain payments. +This allows Spark to fully realize the awesome UX enabled by lightning, +without worrying about the complications and friction of on-chain. +This might change someday. + +Spark has a responsive UI suitable for mobile, tablet and desktop devices, +but is best optimized for use on mobile. > ⚠️ Spark is alpha-quality software under active development. > Please use with care, preferably on testnet or with insignificant amounts. -> Spark comes with no guarantees and with support on a best-effort basis. +> Spark comes with no guarantees, use at your own risk. + +Big shout out to [Blockstream](https://blockstream.com) for generously sponsoring this work! -## Installation +## Server installation -Spark requires a running [c-lightning](https://github.com/ElementsProject/lightning) node +Requires a running [c-lightning](https://github.com/ElementsProject/lightning) node (see setup instructions in [the official docs](https://github.com/ElementsProject/lightning/blob/master/doc/INSTALL.md) or [this tutorial](https://hackernoon.com/harnessing-lightning-for-instant-bitcoin-transacting-a-tutorial-3b9dcdc00552)) -and nodejs (v6.0 or newer). - -Once c-lightning is running, install and start Spark (on the same machine) with: +and nodejs v6.0 or newer (v8 is recommended, see [instructions here](https://nodejs.org/en/download/package-manager/)). ```bash # $ npm install -g spark-wallet @@ -51,25 +71,16 @@ $ npm install -g git+ssh://git@github.com:ElementsProject/spark#dist $ spark-wallet # defaults: --ln-path ~/.lightning --port 9737 ``` -Or simply `$ npx spark-wallet`, which will install and start Spark in one go. -This should normally Just Work ™. +Or simply `$ npx spark-wallet`, which will install and start Spark (with the default args) in one go. Spark will generate and print a random username and password that'll be used to login into the wallet. To specify your own login credentials, set `--login [user]:[pass]` or the `LOGIN` environment variable. To access the wallet, open `http://localhost:9737/` in your browser and login with the username/password. -To accept remote connections, set `--host ` (shorthand `-i`, e.g. `-i 0.0.0.0`). -This will automatically enable TLS ([more details below](#tls)). +See `$ spark-wallet --help` for the full list of command-line options (also available under [*CLI options*](#cli-options)). -Spark can also be accessed using mobile and desktop apps instead of through the browser. -See [*Mobile app (Cordova)*](#mobile-app-cordova) and [*Desktop app (Electron)*](#desktop-app-electron) -for more details. -Note that the desktop app comes bundled with the Spark server and doesn't require the manual server setup described here. - -See `$ spark-wallet --help` for the full list of available options (also available under [*CLI options*](#cli-options)). - -### Configuration file +#### Configuration file Spark reads configuration options from `~/.spark-wallet/config` (can be overridden with `--config/-c `). The expected format is one `key=value` per line, like so: @@ -80,189 +91,100 @@ login=bob:superSecretPassword port=8000 ``` -### Deploy with Docker +#### Connecting remotely -Spark is also available as a Docker image that comes bundled with bitcoind and c-lightning. -See [`doc/docker.md`](https://github.com/ElementsProject/spark/blob/master/doc/docker.md) for more details. +To accept remote connections, set `--host ` (shorthand `-i`, e.g. `-i 0.0.0.0`). +This will automatically enable TLS with a self-signed certificate. -## Features +For more information on TLS, instructions for setting up a CA-signed certificate using the built-in LetsEncrypt integration +and for adding the self-signed certificate to Android, +see [`doc/tls.md`](https://github.com/ElementsProject/spark/blob/master/doc/tls.md). -Spark currently focuses on the core aspects of day-to-day usage: sending, receiving and viewing history. -Peers and channels are expected to be managed using the RPC for now. +To start Spark as a Tor hidden service, set `--onion`. You don't need Tor pre-installed for this to work. +See [`doc/onion.md`](https://github.com/ElementsProject/spark/blob/master/doc/onion.md) for more details, +the advantages of using an hidden service, and instructions for connecting from Android. +*This is highly recommended.* -Spark is a purely off-chain wallet, with no on-chain payments. -This allows Spark to fully realize the awesome UX enabled by lightning, -without worrying about the complications and friction of on-chain. -This might change someday. +#### Deploy with Docker -Spark has a responsive UI suitable for mobile, tablet and desktop devices, -but is best optimized for use on mobile. +Spark is also available as a Docker image that comes bundled with bitcoind and c-lightning. +See [`doc/docker.md`](https://github.com/ElementsProject/spark/blob/master/doc/docker.md) for details. -### Controls +#### Adding to startup with `systemd` -- **Display unit:** Click the balance on the top-right or the unit in the "request payment" page to toggle the currency display unit. - The available options are sat, bits, milli, btc and usd. +See [`doc/startup-systemd.md`](https://github.com/ElementsProject/spark/blob/master/doc/startup-systemd.md). -- **Theme switcher:** Click the theme name on the bottom-right to change themes (you can choose between over 15 [bootswatch](https://bootswatch.com) themes). +## Desktop apps -- **Collapse payments:** Click on payments in the list to display more details. +Electron-based desktop apps for Linux (packaged as `deb`, `AppImage`, `snap` and `tar.gz`), +macOS (as `zip`) and Windows (installer and a portable) are available for download from the +[releases page](https://github.com/ElementsProject/spark/releases). -- **Expert mode:** Click the version number on the bottom-left to toggle expert mode. - This will add [two new menu items](https://user-images.githubusercontent.com/877904/43125383-89ac19b4-8f32-11e8-9a5e-d91eb5a637ea.png), "*Logs*" and - ["*RPC Console*"](https://user-images.githubusercontent.com/877904/43122285-3854be8a-8f29-11e8-9329-d4c5c881c5e2.png), - and display yaml dumps with additional information throughout the app. +The desktop apps comes bundled with the Spark server-side component. If you're connecting to a local +c-lightning instance, you [can configure](https://user-images.githubusercontent.com/877904/44290659-5c224c80-a282-11e8-9433-bb442f11ca88.png) +the desktop app to connect to it directly without manually setting up the Spark server. -### Browser support +Connecting to a remote c-lightning instance requires setting up the Spark server on the same machine +running c-lightning and connecting through it. -Supported on recent desktop and mobile version of Chrome, Firefox and Safari. +## Mobile app -Requires iOS 11+ for WebRTC (used by the QR scanner), but works otherwise with iOS 9+. -Chrome on iOS does not support WebRTC. +A Cordova-based native app for Android is available for download from the +[releases page](https://github.com/ElementsProject/spark/releases) (`spark-wallet-[x.y.z]-android.apk`). +It is not currently published to the app store. -Untested on IE. +The app requires a Spark server to communicate with, which you need [to setup](#server-installation) as a prerequisite. + +When the app starts for the first time, you'll need to configure your Spark server URL and API access key. +You can print your access key to the console by starting Spark with `--print-key/-k`. +You can also scan this information from a QR, which you can get with `--pairing-qr/-Q`. + +For the native app to properly communicate with the server, the TLS certificate has to be +[signed by a CA](https://github.com/ElementsProject/spark/blob/master/doc/tls.md#letsencrypt-integration) +or manually [added as a user trusted certificate](https://github.com/ElementsProject/spark/blob/master/doc/tls.md#add-as-trusted-certificate-to-android). ## Progressive Web App -You can install Spark as a [PWA](https://developer.mozilla.org/en-US/Apps/Progressive) to get a more native-app-like experience, -including an home launcher that opens up in full screen, system notifications and improved page load times. +You can install Spark as a [PWA](https://developer.mozilla.org/en-US/Apps/Progressive) (on mobile and desktop) to get a more native-app-like experience, +including an home launcher that opens up in full screen, system notifications and faster load times. Available in Chrome mobile under `⋮` -> `Add to homescreen` ([see here](https://imgur.com/zVe1sOH)), in Chrome desktop under `More tools` -> `Install to desktop` ([see here](https://i.imgur.com/Pj6FpGA.png)) and in Firefox mobile with an icon next to the address bar ([see here](https://mdn.mozillademos.org/files/15762/add-to-home-screen-icon.png)). -iOS has a [bug](https://github.com/webrtc/samples/issues/933) [preventing](https://stackoverflow.com/questions/46228218/how-to-access-camera-on-ios11-home-screen-web-app/46350136) -PWAs from using WebRTC (used by the QR scanner), but it works otherwise. -The QR scanner works if you access Spark without using the "Add to homescreen" feature. - -Note that installing the PWA on Android requires the TLS certificate to be signed by a CA -or manually added as a user trusted certificate ([instructions below](#add-as-trusted-certificate-to-android)). +Installing the PWA requires TLS and a [CA-signed certificate](https://github.com/ElementsProject/spark/blob/master/doc/tls.md#letsencrypt-integration). -Compared to the PWA, the main advantages of the mobile and desktop apps (below) are +Compared to the PWA, the main advantages of the mobile and desktop apps are the ability to handle `lightning:` URIs, better security sandbox (detached from the browser) and static client-side code. -## Mobile app (Cordova) - -A Cordova-based native app for Android is available for download from the -[releases page](https://github.com/ElementsProject/spark/releases) (`spark.apk`). -It is not currently published to the app store. - -When the app starts for the first time, you'll need to configure your Spark server URL and API access key. -You can print your access key to the console by starting Spark with `--print-key/-k`. -You can also scan this information from a QR, which you can get with `--pairing-qr/-Q`. - -For the native app to properly communicate with the server, the TLS certificate has to be signed by a CA, -or manually added as a user trusted certificate ([instructions below](#add-as-trusted-certificate-to-android)). - -## Desktop app (Electron) - -Electron-based desktop apps for Linux (packaged as `AppImage`, `deb`, `snap` and `tar.gz`), -OS X and Windows are available for download from the -[releases page](https://github.com/ElementsProject/spark/releases). - -The desktop app comes bundled with the Spark server-side component. If you're connecting to a local -c-lightning instance, you can configure the client to connect to it directly without manually setting-up -the Spark server. - -Connecting to a remote c-lightning instance requires setting up the Spark server on the same machine -running c-lightning and connecting through it. - -## TLS - -Spark will by default generate a self-signed certificate and enable TLS when binding on a non-`localhost` address. - -The self-signed certificate and key material will be saved to `~/.spark-wallet/tls/`. -To save to a different location, set `--tls-path`. -To set a custom "common name" for the generated certificate, set `--tls-name` (defaults to the value of `--host`). - -To use your own TLS key and certificate, put your `key.pem` and `cert.pem` files in the `--tls-path` directory. - -To disable TLS and start a plaintext HTTP server instead, set `--no-tls`. -Note that without TLS, Chrome will not allow accessing the camera on non-`localhost` hosts. - -To enable TLS even for `localhost`, set `--force-tls`. - -#### LetsEncrypt integration - -Setting `--letsencrypt ` will automatically register a CA-signed certificate using LetsEncrypt. -This will make your certificate work everywhere without self-signed warnings. - -`$ spark-wallet --host mydomain.com --letsencrypt webmaster@mydomain.com` - -Requires a domain name, cannot be used with IP addresses. -If your domain is different from the host you're binding on, set `--tls-name` -(e.g. `--host 0.0.0.0 --tls-name mydomain.com`). - -Note that verifying domain ownership requires binding an HTTP server on port 80, which normally requires root permissions. -You can either: - -1. Start `spark-wallet` as root (simplest, but not recommended). -2. Use `setcap` to allow nodejs processes to bind on all ports: `$ sudo setcap 'cap_net_bind_service=+ep' $(which node)` -3. Bind the verification server to a different port with `--le-port 8080` (any port >1024 will work), - then forward port 80 to it with `$ sudo iptables -A PREROUTING -t nat -i eth0 -p tcp --dport 80 -j REDIRECT --to-port 8080`. - -After initially verifying your domain, you may start Spark with `--le-noverify` to skip starting the verification server. -This will work until the next renewal is due (every 90 days). - -If you're having troubles, set `--le-debug` to show more debug information. - -#### Add as Trusted Certificate to Android +**Note for iOS users:** iOS [does](https://github.com/webrtc/samples/issues/933) [not](https://stackoverflow.com/questions/46228218/how-to-access-camera-on-ios11-home-screen-web-app/46350136) +allow PWAs to use WebRTC (required for the QR scanner), but it works otherwise. +The QR scanner works if you access Spark without using the PWA "Add to homescreen" feature. -To avoid the self-signed certificate warnings (without a CA), you can add the certificate to your Android's "user trusted certificates" -by following these steps: +## GUI controls -1. Open Spark in your mobile web browser (skipping the warning). -2. Click the red TLS warning in the URL bar to view the certificate and ensure it matches the expected one - (the certificate's SHA1 fingerprint is printed to the console during Spark's startup). -3. Navigate to `/cert.pem` to download the certificate file from the server and open it. -4. You should now see [this screen](https://i.imgur.com/f2DMWdL.png), allowing you to add a user trusted certificate. - Fill in a name (e.g. "Spark"), leave "Used for" on "VPN and apps", and click OK. - -Note that adding a user trusted certificate causes android to display a "Network may be monitored" notification. -It can be flicked off. - -## Tor Onion Hidden Service - -To start Spark as a Tor hidden service (v3), set `--onion`. -Spark will install Tor automatically (via [granax](https://github.com/bookchin/granax)); -you don't have to pre-install anything for this to work. - -Running Spark as a Tor hidden service has the following benefits: - -- Tor onion URLs are self-authenticating and are pinned to your server's public key. -- In addition to authenticating the server, they also serve as a mean to authenticate the user - you can't access the server without knowing the `.onion` hostname. -- You don't have to setup port forwarding, everything is done with outbound connections. - -Tor data files (including secret key material for the hidden service) will be saved to `~/.spark-wallet/tor/`. This can be overridden with `--onion-path`. - -#### Connecting from Android +- **Display unit:** Click the balance on the top-right or the unit in the "request payment" page to toggle the currency display unit. + The available options are sat, bits, milli, btc and usd. -To connect to your hidden service using a web browser, install the -[Orbot](https://guardianproject.info/apps/orbot/) and [Orfox](https://guardianproject.info/apps/orfox/) -applications, open the `.onion` URL in Orfox, and enable JavaScript under `⋮` -> `NoScript`. +- **Theme switcher:** Click the theme name on the bottom-right to change themes (you can choose between over 15 [bootswatch](https://bootswatch.com) themes). -To connect using the Cordova app, configure Orbot to route Spark's traffic over the Tor VPN -(under "Tor-Enabled Apps"), then configure Spark to use the `.onion` server URL. +- **Collapse payments:** Click on payments in the list to display more details. -Instead of manually copying the `.onion` URL, you may want to specify `--print-qr/-q` to print -the URL as a QR to the console, or `--pairing-qr/-Q` to also include the access key. +- **Expert mode:** Click the version number on the bottom-left to toggle expert mode. + This will add [two new menu items](https://user-images.githubusercontent.com/877904/44295422-37919900-a2b1-11e8-93b1-9220cdfc113a.png), "*Logs*" and + ["*RPC Console*"](https://user-images.githubusercontent.com/877904/44295439-7fb0bb80-a2b1-11e8-8506-f5afb1c9f1d7.png), + and display yaml dumps with additional information throughout the app. -## Adding to startup with `systemd` +## Browser support -```bash -# set config options in ~/.spark-wallet/config -$ echo login=bob:superSecretPass123 | tee -a ~/.spark-wallet/config +Supported on recent desktop and mobile version of Chrome, Firefox and Safari. +IE is unsupported. -# create service file from template -$ curl -s https://raw.githubusercontent.com/ElementsProject/spark/master/scripts/spark-wallet.service | - sed "s~{cmd}~`which spark-wallet`~;s~{user}~`whoami`~" | - sudo tee /etc/systemd/system/spark-wallet.service +Requires iOS 11+ for WebRTC (used by the QR scanner), but works otherwise with iOS 9+. +Chrome on iOS does not support WebRTC. -# inspect the generated service file, then load and start the service with: -$ sudo systemctl daemon-reload -$ sudo systemctl enable spark-wallet && sudo systemctl start spark-wallet -``` ## Developing @@ -287,7 +209,7 @@ To get more verbose output in the browser developer console, set `localStorage.d Pull requests, suggestions and comments and welcome! -## Code signing & Reproducible builds +## Code signing & reproducible builds Signed distribution checksums are available in the git repo at [`SHA256SUMS.asc`](https://github.com/ElementsProject/spark/blob/master/SHA256SUMS.asc) @@ -302,15 +224,14 @@ The public key can be verified on [keybase](https://keybase.io/nadav), [HN](https://news.ycombinator.com/user?id=nadaviv) or on [a domain he's known to control](https://www.bitrated.com/.keys/staff/nadav.asc). -To install the signed NPM package, rather than downloading it from the NPM registry, download it from +To install the signed NPM package, download it from [the releases page](https://github.com/ElementsProject/spark/releases), verify the hash -and install using `$ npm install -g spark-wallet-[x.y.z]-npm.tgz`, -or install it from a signed git commit hash using `$ npm install -g github:ElementsProject/spark#[commit-hash-verified-to-be-signed]`. +and install using `$ npm install -g spark-wallet-[x.y.z]-npm.tgz`. To install the signed Docker image, get the image hash from `SHA256SUMS.asc` and install it with `$ docker pull shesek/spark@sha256:[image-hash-verified-by-be-signed]`. -The distribution checksums for the NPM package, Android `apk` builds, Linux `tar.gz`/`deb`/`snap` builds, macOS `zip` builds and Windows builds (installer and portable) +The NPM package, Android `apk` builds, Linux `tar.gz`/`deb`/`snap` builds, macOS `zip` builds and Windows builds (installer and portable) [are deterministically reproducible](https://github.com/ElementsProject/spark/blob/master/doc/reproducible-builds.md). ## CLI options @@ -326,9 +247,9 @@ $ spark-wallet --help Options -l, --ln-path path to c-lightning data directory [default: ~/.lightning] -u, --login http basic auth login, "username:password" format [default: generate random] - -p, --port http(s) server port [default: 9737] -i, --host http(s) server listen address [default: localhost] + --no-webui run API server without serving client assets [default: false] --force-tls enable TLS even when binding on localhost [default: enable for non-localhost only] --no-tls disable TLS for non-localhost hosts [default: false] @@ -336,13 +257,12 @@ $ spark-wallet --help --tls-name common name for the TLS cert [default: {host}] --letsencrypt enable CA-signed certificate via LetsEncrypt [default: false] - -o, --onion start Tor Hidden Service (v3) [default: false] - -O, --onion-path directory to read/store hidden service data [default: ~/.spark-wallet/tor/] - -k, --print-key print access key to console (for use with the Cordova/Electron apps) [default: false] -q, --print-qr print QR code with the server URL [default: false] -Q, --pairing-qr print QR code with embedded access key [default: false] - --no-webui run API server without serving client assets [default: false] + + -o, --onion start Tor Hidden Service (v3) [default: false] + -O, --onion-path directory to read/store hidden service data [default: ~/.spark-wallet/tor/] -c, --config path to config file [default: ~/.spark-wallet/config] -V, --verbose display debugging information [default: false] @@ -358,4 +278,4 @@ $ spark-wallet --help ## License -MIT +[MIT](https://github.com/ElementsProject/spark/blob/master/LICENSE) diff --git a/doc/docker.md b/doc/docker.md index 07b7db5..cad649b 100644 --- a/doc/docker.md +++ b/doc/docker.md @@ -3,7 +3,7 @@ You can use Docker To setup Spark, a bitcoind node and a c-lightning node all in go with the following command: ```bash -$ docker run -v $HOME/.spark-docker:/data -p 9737:9737 \ +$ docker run -v ~/.spark-docker:/data -p 9737:9737 \ shesek/spark --login bob:superSecretPass456 ``` @@ -12,7 +12,7 @@ You will then be able to access the Spark wallet at `https://localhost:9737`. Runs in `testnet` mode by default, set `NETWORK` to override (e.g. `-e NETWORK=bitcoin`). Data files will be stored in `~/.spark-docker/{bitcoin,lightning,spark}`. -You cat set Spark's configuration options in `~/.spark-docker/spark/config`. +You can set Spark's configuration options in `~/.spark-docker/spark/config`. When starting for the first time, you'll have to wait for the bitcoin node to sync up. You can check the progress by tailing `~/.spark-docker/bitcoin/debug.log`. @@ -29,8 +29,8 @@ To connect to an existing `lightningd` instance running on the same machine, mount the lightning data directory to `/etc/lightning`: ```bash -$ docker run -v $HOME/.spark-docker:/data -p 9737:9737 \ - -v $HOME/.lightning:/etc/lightning \ +$ docker run -v ~/.spark-docker:/data -p 9737:9737 \ + -v ~/.lightning:/etc/lightning \ shesek/spark ``` @@ -39,7 +39,7 @@ Connecting to remote lightningd instances is currently not supported. #### With existing `bitcoind`, but with bundled `lightningd` To connect to an existing `bitcoind` instance running on the same machine, -mount the bitcoin data directory to `/etc/bitcoin` (e.g. `-v $HOME/.bitcoin:/etc/bitcoin`), +mount the bitcoin data directory to `/etc/bitcoin` (e.g. `-v ~/.bitcoin:/etc/bitcoin`), and either use host networking (`--network host`) or specify the IP where bitcoind is reachable via `BITCOIND_RPCCONNECT`. The RPC credentials and port will be read from bitcoind's config file. diff --git a/doc/onion.md b/doc/onion.md new file mode 100644 index 0000000..899a95a --- /dev/null +++ b/doc/onion.md @@ -0,0 +1,30 @@ +# Tor Onion Hidden Service + +To start Spark as a Tor hidden service (v3), set `--onion`. +Spark will install Tor automatically (via [granax](https://gitlab.com/bookchin/granax)/[hsv3](https://gitlab.com/bookchin/hsv3)); +you don't have to pre-install anything for this to work. + +Running Spark as a Tor hidden service has the following benefits: + +- Tor `.onion` hostnames are self-authenticating and are pinned to your server's public key. + +- In addition to authenticating the server, they also serve as a mean to authenticate the user - you can't access the server without knowing the `.onion` hostname. + That means that even if a security vulnerability is found on nodejs/Spark, + an attacker will not be able the access to server in order to exploit it. + +- You don't have to setup port forwarding, everything is done with outbound connections. + Punch through routers with ease. + +Tor data files (including secret key material for the hidden service) will be saved to `~/.spark-wallet/tor/`. This can be overridden with `--onion-path`. + +### Connecting from Android + +To connect to your hidden service using a web browser, install the +[Orbot](https://guardianproject.info/apps/orbot/) and [Orfox](https://guardianproject.info/apps/orfox/) +applications, open the `.onion` URL in Orfox, and enable JavaScript under `⋮` -> `NoScript`. + +To connect using the Cordova app, configure Orbot to route Spark's traffic over the Tor VPN +(under "Tor-Enabled Apps"), then configure Spark to use the `.onion` server URL. + +Instead of manually copying the `.onion` URL, you may want to specify `--print-qr/-q` to print +the URL as a QR to the console, or `--pairing-qr/-Q` to also include the access key. diff --git a/doc/startup-systemd.md b/doc/startup-systemd.md new file mode 100644 index 0000000..77c7be3 --- /dev/null +++ b/doc/startup-systemd.md @@ -0,0 +1,15 @@ +# Adding Spark to startup with `systemd` + +```bash +# Set config options in ~/.spark-wallet/config +$ echo login=bob:superSecretPass123 | tee -a ~/.spark-wallet/config + +# Create service file from template +$ curl -s https://raw.githubusercontent.com/ElementsProject/spark/master/scripts/spark-wallet.service | + sed "s~{cmd}~`which spark-wallet`~;s~{user}~`whoami`~" | + sudo tee /etc/systemd/system/spark-wallet.service + +# Inspect the generated service file, then load and start the service +$ sudo systemctl daemon-reload +$ sudo systemctl enable spark-wallet && sudo systemctl start spark-wallet +``` diff --git a/doc/tls.md b/doc/tls.md new file mode 100644 index 0000000..1e324e4 --- /dev/null +++ b/doc/tls.md @@ -0,0 +1,59 @@ +# TLS + +Spark will by default generate a self-signed certificate and enable TLS when binding on a non-`localhost` address. + +The self-signed certificate and key material will be saved to `~/.spark-wallet/tls/`. +To save to a different location, set `--tls-path`. +To set a custom "common name" for the generated certificate, set `--tls-name` (defaults to the value of `--host`). + +To use your own TLS key and certificate, put your `key.pem` and `cert.pem` files in the `--tls-path` directory. + +To disable TLS and start a plaintext HTTP server instead, set `--no-tls`. +Note that without TLS, Chrome will not allow accessing the camera on non-`localhost` hosts. + +To enable TLS even for `localhost`, set `--force-tls`. + +### LetsEncrypt integration + +Setting `--letsencrypt ` will automatically setup a CA-signed certificate using LetsEncrypt. +This will make your certificate work everywhere without self-signed warnings. + +``` +$ spark-wallet --host mydomain.com --letsencrypt webmaster@mydomain.com +``` + +Requires a (sub)domain name, cannot be used with IP addresses. +If your domain is different from the host you're binding on, set `--tls-name` +(e.g. `--host 0.0.0.0 --tls-name mydomain.com`). + +Note that verifying domain ownership requires binding an HTTP server on port 80, which normally requires root permissions. +You can either: + +1. Start `spark-wallet` as root (simplest, but not recommended). +2. Use `setcap` to allow nodejs processes to bind on all ports: `$ sudo setcap 'cap_net_bind_service=+ep' $(which node)` +3. Bind the verification server to a different port with `--le-port 8080` (any port >1024 will work), then forward port 80 to it with: + `$ iptables -A PREROUTING -t nat -p tcp --dport 80 -j REDIRECT --to-port 8080 && iptables -t nat -A OUTPUT -o lo -p tcp --dport 80 -j DNAT --to-destination :8080` + +After initially verifying your domain, you may start Spark with `--le-noverify` to skip starting the verification server. +This will work until the next renewal is due (every 90 days). + +If you're having troubles, set `--le-debug` to show more debug information. + +### Add as Trusted Certificate to Android + +To avoid the self-signed certificate warnings (without a CA), you can add the certificate to your Android's "user trusted certificates" +by following these steps: + +1. Open Spark in your mobile web browser (skipping the warning). +2. Click the red TLS warning in the URL bar to view the certificate and ensure it matches the expected one + (the certificate's SHA1 fingerprint is printed to the console during Spark's startup). +3. Navigate to `/cert.pem` to download the certificate file from the server and open it. +4. You should now see [this screen](https://i.imgur.com/f2DMWdL.png), allowing you to add a user trusted certificate. + Fill in a name (e.g. "Spark"), leave "Used for" on "VPN and apps", and click OK. + +Note that adding a user trusted certificate causes android to display a "Network may be monitored" notification. +It can be flicked off. + +Unfortunately, adding a user trusted certificate is not enough for Android to allow installing the PWA. +This requires a CA-signed certificate. + diff --git a/src/cli.js b/src/cli.js index 52b1a0a..bb8dc04 100755 --- a/src/cli.js +++ b/src/cli.js @@ -7,9 +7,9 @@ const args = require('meow')(` Options -l, --ln-path path to c-lightning data directory [default: ~/.lightning] -u, --login http basic auth login, "username:password" format [default: generate random] - -p, --port http(s) server port [default: 9737] -i, --host http(s) server listen address [default: localhost] + --no-webui run API server without serving client assets [default: false] --force-tls enable TLS even when binding on localhost [default: enable for non-localhost only] --no-tls disable TLS for non-localhost hosts [default: false] @@ -24,8 +24,6 @@ const args = require('meow')(` -o, --onion start Tor Hidden Service (v3) [default: false] -O, --onion-path directory to read/store hidden service data [default: ~/.spark-wallet/tor/] - --no-webui run API server without serving client assets [default: false] - -c, --config path to config file [default: ~/.spark-wallet/config] -V, --verbose display debugging information [default: false] -h, --help output usage information diff --git a/src/transport/tls.js b/src/transport/tls.js index b5d9452..b07835e 100644 --- a/src/transport/tls.js +++ b/src/transport/tls.js @@ -86,7 +86,7 @@ const letsencrypt = (name, dir, email) => { if (err.errno == 'EACCES') { console.error(`\nYou don't have prmission to bind on ${err.address}:${err.port}.`); - console.error('See https://github.com/ElementsProject/spark/blob/master/README.md#letsencrypt-integration for advice.'); + console.error('See https://github.com/ElementsProject/spark/blob/master/doc/tls.md#letsencrypt-integration for advice.'); } else if (err.errno == 'EADDRINUSE') { console.error(`\n${err.address}:${err.port} is already being used by some other program. Stop it and try again.`); }