thehub/wallet-store-server

Wallet storage server.

The Flowee wallet storage server is specialized in taking POST requests to submit formatted wallet store-files, verifying they are encrypted and signed. And using GET/HEAD to fetch those files based on their identity (bitcoin cash address).

By default this server will simply bind to localhost, port 80. It has no support for SSL. To plug it into your bigger website and use SSL (useful for privacy reasons) you can run it behind an NGINX proxy.

nginx config block:

    location /md {
        proxy_pass http://localhost:42121/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

The example walletStorage.conf file can be placed in the default XDG place for the user it will be executed on, for instance /home/flowee/.config/flowee/walletStorage.conf or /etc/xdg/flowee/walletStorage.conf or you can alter the systemd file to pass the path.

An example logs.conf can be;

/home/flowee/.config/flowee/wallet-storage-server/logs.conf

channel file
   option timestamp time date
   option path /home/flowee/logs/walletStorageServer.log`

Client usage

This server only accepts well formed wallet storage, as created by Flowee Pay and likely in the future other wallets.

We expect the storage to be encrypted, and this server won't touch the actual data, but the encrypted payload should be embedded in an envelope with the following properties:

name	type	size
timestamp	int	4 bytes
data-size	int	4 bytes
data	bytearray	data-size bytes
signature	bytearray	65 bytes

The timestamp is unix-epoch type, an unsigned int that should be good enough for another several decades. The server uses the timestamp to sort uploads, the most recent one is always the first listed.

The data is ignored by this server. We just store it as it is expected to be encrypted when it arrives on the server.

The signature is a secp256k1 curve 'compact' signature. It is expected to sign the entire file (from timestamp up until the signature). A compact signature allows the public key to be retrieved and the server will use that to turn that into a bitcoin cash style address and make the file available for download under that key.

Naturally, uploads just use the simple HTTP POST protocol, we advice sys admins to place this behind a https site, as described in the nginx config option at the top of this file.

Actual downloads likewise use the https site and pass as part of the url the address the user wants to fetch a storage for.

Using the url like:

https://flowee.org/md/q-address

returns a JSON with the list of available files. Example JSON:

{
 "1": "1762272915",
 "2": "1762041600"
}

Or a direct download can be like:

https://flowee.org/md/q-address/1 or https://flowee.org/md/q-address/1762272915, which in this case lead to the same download.

We intentionally do not provide any way to list all known addresses.