nws/README.md

109 lines
3.8 KiB
Markdown
Raw Normal View History

2024-07-22 21:00:21 +00:00
# Nostr Web Services (NWS)
NWS replaces the IP layer in TCP transport using Nostr, enabling a secure connection between
clients and backend services.
Exit nodes are reachable through their [nprofiles](https://nostr-nips.com/nip-19), which are combinations of a Nostr public key and multiple relays.
### Prerequisites
- A list of Nostr relays that the exit node is connected to.
- The Nostr private key of the exit node.
The exit node utilizes the private key and relay list to generate an [nprofile](https://nostr-nips.com/nip-19), which is printed in the console on startup.
## Overview
### NWS main components
1. **Entry node**: It forwards tcp packets to the exit node using a SOCKS proxy and creates encrypted events for the public key of the exit node.
2. **Exit node**: It is a TCP reverse proxy that listens for incoming Nostr subscriptions and forwards the payload to the designated backend service.
<img src="nws.png" width="900"/>
## Quickstart
Running NWS using Docker is recommended. For instructions on running NWS on your local machine, refer to the [Build from source](#build-from-source) section.
### Using Docker Compose
Please navigate to the `docker-compose.yaml` file and set the value of `NOSTR_PRIVATE_KEY` to your own private key.
Leaving it empty will generate a new private key on startup.
2024-07-22 21:00:21 +00:00
To set up using Docker Compose, run the following command:
```
docker compose up -d --build
```
This will start an example setup, including the entry node, exit node, and a backend service.
You can run the following commands to receive your nprofiles:
```bash
docker logs exit-https 2>&1 | awk -F'profile=' '{if ($2) print $2}' | awk '{print $1}
```
```bash
docker logs exit 2>&1 | awk -F'profile=' '{if ($2) print $2}' | awk '{print $1}
```
2024-07-22 21:00:21 +00:00
### Sending Requests to the Entry node
With the log information from the previous step, you can use the following command to send a request to the nprofile:
2024-07-22 21:00:21 +00:00
```
curl -v -x socks5h://localhost:8882 http://"$(docker logs exit 2>&1 | awk -F'profile=' '{if ($2) print $2}' | awk '{print $1}')"/v1/info --insecure
2024-07-22 21:00:21 +00:00
```
If the nprofile supports TLS, you can choose to connect using https scheme
```
curl -v -x socks5h://localhost:8882 https://"$(docker logs exit-https 2>&1 | awk -F'profile=' '{if ($2) print $2}' | awk '{print $1}')"/v1/info --insecure
2024-07-22 21:00:21 +00:00
```
When using https, the entry node can be used as a service, since the operator will not be able to see the request data.
## Build from source
The exit node must be set up to make the services reachable via Nostr.
### Configuration
Configuration can be completed using environment variables.
Alternatively, you can create a `.env` file in the current working directory with the following content:
```
NOSTR_RELAYS = 'ws://localhost:6666;wss://relay.damus.io'
NOSTR_PRIVATE_KEY = "EXITPRIVATEHEX"
BACKEND_HOST = 'localhost:3338'
```
- `NOSTR_RELAYS`: A list of nostr relays to publish events to. Will only be used if there was no nprofile in the
request.
- `NOSTR_PRIVATE_KEY`: The private key to sign the events
- `BACKEND_HOST`: The host of the backend to forward requests to
To start the exit node, use this command:
```
go run cmd/exit/main.go
```
If your backend services support TLS, your service can now start using TLS encryption through a publicly available entry node.
---
To run an entry node for accessing NWS services behind exit nodes, use the following command:
```
go run cmd/proxy/main.go
```
#### Entry node Configuration
If you used environment variables, no further configuration is needed.
For `.env` file configurations, do so in the current working directory with the following content:
```
NOSTR_RELAYS = 'ws://localhost:6666;wss://relay.damus.io'
```
Here, NOSTR_RELAYS is a list of nostr relays to publish events to and will only be used if there was no nprofile in the request.