Update docs and CLI help

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

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.
 

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.

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
+```

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 <email>` 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.
+

src/cli.js

@@ -7,9 +7,9 @@ const args = require('meow')(`
     Options
       -l, --ln-path <path>     path to c-lightning data directory [default: ~/.lightning]
       -u, --login <userpwd>    http basic auth login, "username:password" format [default: generate random]
-
       -p, --port <port>        http(s) server port [default: 9737]
       -i, --host <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 <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>      path to config file [default: ~/.spark-wallet/config]
       -V, --verbose            display debugging information [default: false]
       -h, --help               output usage information

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.`);
       }