Skip to content

Commit 567dbc6

Browse files
tankyleotankyleo
committed
Document VSS setup and auth configuration
Fixes #53
1 parent 5ba5451 commit 567dbc6

3 files changed

Lines changed: 154 additions & 44 deletions

File tree

‎README.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -70,12 +70,12 @@ VSS is also integrated with [LDK-node] v0.4.x as alpha support.
7070

7171
### Development
7272

73-
* **Build & Deploy**: Refer to [docs/getting-started.md](docs/getting-started.md) for instructions related to
74-
building and deploying VSS.
73+
* **Build & Deploy**: Refer to [docs/getting-started.md](docs/getting-started.md) for concrete PostgreSQL setup,
74+
authentication configuration, local no-auth development mode, and deployment commands.
7575
* **Hosting**: VSS can either be self-hosted or deployed in the cloud. If a service provider is hosting VSS for multiple
7676
users, it must be configured with **HTTPS**, **Authentication/Authorization**, and **rate-limiting**.
7777
* **Authentication and Authorization**: VSS supports authentication via
78-
[Proof-of-Private-Key-Knowledge](#Authentication) or [JWT](https://datatracker.ietf.org/doc/html/rfc7519).
78+
[Proof-of-Private-Key-Knowledge](#authentication) or [JWT](https://datatracker.ietf.org/doc/html/rfc7519).
7979
The API also offers hooks for simple HTTP header-based authentication. Note that the security of authentication
8080
heavily relies on using HTTPS for all requests.
8181
* **Scaling**: VSS itself is stateless and can be horizontally scaled easily. VSS can be configured to point to a
@@ -99,18 +99,19 @@ VSS is also integrated with [LDK-node] v0.4.x as alpha support.
9999

100100
### Authentication
101101

102-
By default, VSS uses a simple authentication scheme whereby each client must provide a valid signature for a
103-
client-specified public key. The public key identifies the storage that belongs to the client. This scheme does
104-
not impose **any** restrictions on who can interact with VSS; it **only** ensures that each client can only
105-
access *their own* storage. Therefore, this scheme **must** be paired with a network-level gatekeeper to prevent
106-
unauthorized interactions with VSS.
102+
Default builds include signature and JWT authentication. If `jwt_auth_config.rsa_pem` or `VSS_JWT_RSA_PEM` is
103+
configured, VSS verifies RS256 bearer tokens from the HTTP `Authorization` header. The JWT `sub` claim identifies
104+
the storage user. VSS only implements token verification; operators must provide their own token issuance service.
107105

108-
The other option offered is JWT authentication. This form of authentication validates whether a client should
109-
be given access to VSS, *and* which storage the client has access to. VSS only implements the verification half of this
110-
scheme, and users must provide their own JWT issuance service if this solution is chosen.
106+
If JWT is not configured, VSS uses signature authentication. Each client provides a valid signature for a
107+
client-specified secp256k1 public key in the HTTP `Authorization` header. The public key identifies that client's
108+
storage. This scheme does not impose **any** restrictions on who can interact with VSS; it **only** ensures that each
109+
client can only access *their own* storage. Therefore, this scheme **must** be paired with a network-level gatekeeper
110+
and rate limiting to prevent unauthorized interactions with VSS.
111111

112-
Finally, there is an option to completely disable all forms of authentication to VSS. This option should *only* be
113-
used in local development and testing.
112+
Finally, there is a cfg-gated option to disable all forms of authentication for local development and testing. Do not
113+
publicly expose no-auth builds. See [docs/getting-started.md](docs/getting-started.md#authentication-setup) for exact
114+
config and build commands.
114115

115116
### Summary
116117

‎docs/getting-started.md‎

Lines changed: 131 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,145 @@
1-
# Versioned Storage Service (Rust)
1+
# Getting Started
22

3-
### Prerequisites
3+
This guide covers a local source build and the required PostgreSQL and authentication setup. For
4+
the threat model and auth overview, see the root [README](../README.md).
45

5-
- Install Rust and Cargo (https://www.rust-lang.org/tools/install).
6-
- Install PostgreSQL 15 (https://www.postgresql.org/download/)
7-
- Install OpenSSL (used for TLS connections to the PostgreSQL backend: https://docs.rs/openssl/latest/openssl/#automatic)
6+
## Prerequisites
87

9-
### Building
8+
- Rust and Cargo, using at least the repository MSRV of 1.85.0.
9+
- PostgreSQL 15 or newer.
10+
- OpenSSL development/runtime libraries for PostgreSQL TLS support.
1011

11-
```
12-
git clone https://github.com/lightningdevkit/vss-server.git
13-
cd vss-server
12+
## Quick Start with Docker PostgreSQL
13+
14+
Start only the PostgreSQL service from the included Compose file:
1415

16+
```bash
17+
docker compose up -d postgres
1518
cargo build --release
19+
cargo run -- server/vss-server-config.toml
20+
```
21+
22+
The sample config connects to `postgres:postgres@127.0.0.1:5432`, creates the `vss` database if it
23+
does not exist, and runs schema migrations on startup. The VSS endpoint is
24+
`http://localhost:8080/vss`; `/metrics` is available without VSS authentication:
25+
26+
```bash
27+
curl -f http://localhost:8080/metrics
28+
```
29+
30+
The default `cargo run` command starts the server with signature authentication, because the sample
31+
config does not include a JWT key. VSS API requests still need a valid `Authorization` header. To
32+
exercise VSS API endpoints without auth headers in a local-only environment, use
33+
[Local No-Auth Mode](#local-no-auth-mode).
34+
35+
To run both PostgreSQL and the server in containers:
36+
37+
```bash
38+
docker compose up --build
1639
```
1740

18-
### Running
19-
1. **Edit Configuration**: Modify `./server/vss-server-config.toml` to set application configuration and
20-
environment variables as needed.
21-
2. VSS will setup a PostgreSQL database on first launch if it is not found. You can also manually create the database
22-
using the statement at `./impls/src/postgres/sql/v0_create_vss_db.sql`.
23-
3. Start server:
24-
```
25-
cargo run server/vss-server-config.toml
26-
```
27-
4. VSS endpoint should be reachable at `http://localhost:8080/vss`.
41+
## PostgreSQL Setup
42+
43+
VSS first connects to `default_database`, then creates `vss_database` if it is missing, then connects
44+
to `vss_database` and applies migrations. With the sample config these are `postgres` and `vss`.
45+
46+
The configured PostgreSQL role must be able to connect to `default_database`. It must also either:
47+
48+
- have permission to run `CREATE DATABASE vss` when `vss_database` does not exist, or
49+
- use an already-created `vss_database` and have privileges to create/alter tables, indexes,
50+
sequences, and rows in that database.
51+
52+
For an existing local PostgreSQL instance, create the database yourself if the VSS user cannot create
53+
databases:
54+
55+
```bash
56+
createdb -U postgres vss
57+
```
58+
59+
Then update `[postgresql_config]` in `server/vss-server-config.toml` or set the corresponding
60+
environment variables:
61+
62+
```bash
63+
VSS_PSQL_USERNAME=postgres
64+
VSS_PSQL_PASSWORD=postgres
65+
VSS_PSQL_ADDRESS=127.0.0.1:5432
66+
VSS_PSQL_DEFAULT_DB=postgres
67+
VSS_PSQL_VSS_DB=vss
68+
```
69+
70+
## Authentication Setup
71+
72+
Default builds include both `jwt` and `sigs` features. At startup, VSS uses JWT auth if an RSA public
73+
key is configured; otherwise it uses signature auth. Both schemes read the HTTP `Authorization`
74+
header.
75+
76+
### Signature Auth
77+
78+
No TOML setting is required. Leave `[jwt_auth_config]` unset and the default build will require each
79+
request to include a proof of private key knowledge in `Authorization`. The proof is the compressed
80+
secp256k1 public key hex, followed by a compact ECDSA signature hex, followed by a Unix timestamp.
81+
The signature covers VSS's signing constant, the public key, and the timestamp. Signature auth
82+
isolates storage by public key, but does not decide who may create a new storage identity;
83+
production deployments still need HTTPS, rate limiting, and an external access control layer.
84+
85+
### JWT Auth
86+
87+
Configure the RSA public key used to verify RS256 JWTs:
88+
89+
```toml
90+
[jwt_auth_config]
91+
rsa_pem = """
92+
-----BEGIN PUBLIC KEY-----
93+
...
94+
-----END PUBLIC KEY-----
95+
"""
96+
```
97+
98+
or set `VSS_JWT_RSA_PEM`. Clients must send `Authorization: Bearer <jwt>`. Tokens must be RS256,
99+
include `sub` and `exp` claims, and omit `aud`; `sub` becomes the VSS storage user token. VSS only
100+
verifies tokens, you must run the service that issues them.
101+
102+
### Local No-Auth Mode
103+
104+
For local development only, build with the cfg-gated no-op authorizer:
105+
106+
```bash
107+
RUSTFLAGS="--cfg noop_authorizer" cargo run --no-default-features -- server/vss-server-config.toml
108+
```
109+
110+
Do not expose this mode outside a local test environment.
111+
112+
## Configuration Reference
113+
114+
Default builds read the following settings. Each listed TOML option can be overridden by its
115+
environment variable.
116+
117+
| TOML setting | Environment variable | Purpose |
118+
| --- | --- | --- |
119+
| `server_config.bind_address` | `VSS_BIND_ADDRESS` | HTTP listen address, for example `127.0.0.1:8080`. |
120+
| `server_config.max_request_body_size` | `VSS_MAX_REQUEST_BODY_SIZE` | Request body limit in bytes. Defaults to 1 GiB. |
121+
| `jwt_auth_config.rsa_pem` | `VSS_JWT_RSA_PEM` | RSA public key for JWT verification. Requires the `jwt` feature, which is enabled by default. |
122+
| `postgresql_config.username` | `VSS_PSQL_USERNAME` | PostgreSQL user. |
123+
| `postgresql_config.password` | `VSS_PSQL_PASSWORD` | PostgreSQL password. |
124+
| `postgresql_config.address` | `VSS_PSQL_ADDRESS` | PostgreSQL host and port. |
125+
| `postgresql_config.default_database` | `VSS_PSQL_DEFAULT_DB` | Database used for startup and database creation. |
126+
| `postgresql_config.vss_database` | `VSS_PSQL_VSS_DB` | VSS application database. |
127+
| `postgresql_config.tls` | `VSS_PSQL_TLS` | Enables PostgreSQL TLS with system trust roots. |
128+
| `postgresql_config.tls.crt_pem` | `VSS_PSQL_CRT_PEM` | Adds a PEM root certificate and enables PostgreSQL TLS. |
129+
| `log_config.level` | `VSS_LOG_LEVEL` | Log level. Defaults to `debug`. |
130+
| `log_config.file` | `VSS_LOG_FILE` | Log file path. Defaults to `vss.log`. |
28131

29-
### Configuration
132+
## Production Notes
30133

31-
Refer to `./server/vss-server-config.toml` to see available configuration options.
134+
VSS is stateless and can be run behind a load balancer, but PostgreSQL is the durable state store.
135+
Internet-facing deployments must terminate HTTPS in front of VSS, configure authentication, and add
136+
rate limiting.
32137

33-
### Support
138+
## Support
34139

35-
If you encounter any issues or have questions, feel free to open an issue on
36-
the [GitHub repository](https://github.com/lightningdevkit/vss-server/issues). For further assistance or to discuss the
37-
development of VSS, you can reach out to us in the [LDK Discord](https://discord.gg/5AcknnMfBw) in the `#vss` channel.
140+
Open issues in the [GitHub repository](https://github.com/lightningdevkit/vss-server/issues), or use
141+
the [LDK Discord](https://discord.gg/5AcknnMfBw) `#vss` channel.
38142

39-
[LDK Discord]: https://discord.gg/5AcknnMfBw
143+
## MSRV
40144

41-
### MSRV
42-
The Minimum Supported Rust Version (MSRV) is currently 1.85.0.
145+
The Minimum Supported Rust Version (MSRV) is 1.85.0.

‎server/vss-server-config.toml‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,14 @@ bind_address = "127.0.0.1:8080" # Optional in TOML, can be overridden by env var
44
# Defaults to the maximum possible value of 1 GB if unset.
55
# max_request_body_size = 1073741824
66

7-
# Uncomment the table below to verify JWT tokens in the HTTP Authorization header against the given RSA public key,
8-
# can be overridden by env var `VSS_JWT_RSA_PEM`
7+
# Authentication:
8+
# - Default builds use signature auth when this JWT section is unset. Signature auth has no TOML
9+
# setting; clients must send the required signature in the HTTP Authorization header.
10+
# - Uncomment the table below to use JWT auth instead. JWT auth verifies Bearer tokens in the
11+
# HTTP Authorization header against this RSA public key, and can be overridden by env var
12+
# `VSS_JWT_RSA_PEM`.
13+
# - For local development only, no-auth mode requires building with:
14+
# RUSTFLAGS="--cfg noop_authorizer" cargo run --no-default-features -- server/vss-server-config.toml
915
# [jwt_auth_config]
1016
# rsa_pem = """
1117
# -----BEGIN PUBLIC KEY-----
@@ -31,4 +37,4 @@ vss_database = "vss" # Optional in TOML, can be overridden by env var
3137

3238
# [log_config]
3339
# level = "debug" # Uncomment, or set env var `VSS_LOG_LEVEL` to set the log level, the default is "debug"
34-
# file = "vss.log" # Uncomment, or set env var `VSS_LOG_FILE` to set the log file path, the default is "vss.log"
40+
# file = "vss.log" # Uncomment, or set env var `VSS_LOG_FILE` to set the log file path, the default is "vss.log"

0 commit comments

Comments
 (0)