From 270753fadd06d3fc04318492e079e77964a2a5a5 Mon Sep 17 00:00:00 2001 From: Leo Nash Date: Fri, 23 Jan 2026 02:12:59 +0000 Subject: [PATCH] Document OpenSSL dependency, Private-Key-Knowledge authentication Also document the automatic creation of the database if it does not exist. --- README.md | 26 ++++++++++++++++++++------ rust/README.md | 8 +++++--- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d5f0bce..0685e1b 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ See the [VSS API contract] for details. ### Implementation -Currently, VSS-server has a Rust-based implementation and is ready to use. +VSS has a Rust-based implementation and is ready to use. [VSS-rust-client] is a Rust-based client with support for client-side encryption, key obfuscation, retry mechanisms, and LNURL-auth. VSS is also integrated with [LDK-node] v0.4.x as alpha support. @@ -72,11 +72,10 @@ VSS is also integrated with [LDK-node] v0.4.x as alpha support. * **Build & Deploy**: Refer to language-specific folder for instructions related to building and deploying VSS. * **Hosting**: VSS can either be self-hosted or deployed in the cloud. If a service provider is hosting VSS for multiple users, it must be configured with **HTTPS**, **Authentication/Authorization**, and **rate-limiting**. -* **Authentication and Authorization**: Currently, the VSS-server - supports [JWT](https://datatracker.ietf.org/doc/html/rfc7519)-based authentication and authorization, and can run - without authentication for local testing or in trusted setups. The VSS-rust-client supports LNURL-auth & JWT based - authentication and authorization. Switching to simple HTTP header authentication is straightforward by adding another - implementation. Note that the security of authentication heavily relies on using HTTPS for all requests. +* **Authentication and Authorization**: VSS supports authentication via + [Proof-of-Private-Key-Knowledge](#Authentication) or [JWT](https://datatracker.ietf.org/doc/html/rfc7519). + The API also offers hooks for simple HTTP header-based authentication. Note that the security of authentication + heavily relies on using HTTPS for all requests. * **Scaling**: VSS itself is stateless and can be horizontally scaled easily. VSS can be configured to point to a PostgreSQL cluster, and further scaling considerations need to be addressed in the PostgreSQL cluster. * **Using with LDK-node**: [LDK-node] can be easily configured to run with VSS as primary storage. It is integrated in @@ -96,6 +95,21 @@ VSS is also integrated with [LDK-node] v0.4.x as alpha support. the [VSS-rust-client] directly for this purpose. This can help provide a complete user data recovery solution for applications, as well as enable turn-key multi-device support in the future. +### Authentication + +By default, VSS uses a simple authentication scheme whereby each client must provide a valid signature for a +client-specified public key. The public key identifies the storage that belongs to the client. This scheme does +not impose **any** restrictions on who can interact with VSS; it **only** ensures that each client can only +access *their own* storage. Therefore, this scheme **must** be paired with a network-level gatekeeper to prevent +unauthorized interactions with VSS. + +The other option offered is JWT authentication. This form of authentication validates whether a client should +be given access to VSS, *and* which storage the client has access to. VSS only implements the verification half of this +scheme, and users must provide their own JWT issuance service if this solution is chosen. + +Finally, there is an option to completely disable all forms of authentication to VSS. This option should *only* be +used in local development and testing. + ### Summary In summary, VSS is an open-source project that offers a server-side cloud storage solution for non-custodial Lightning diff --git a/rust/README.md b/rust/README.md index 7b9b96c..1a998ee 100644 --- a/rust/README.md +++ b/rust/README.md @@ -6,6 +6,7 @@ This directory hosts the Rust-based implementation of the Versioned Storage Serv - Install Rust and Cargo (https://www.rust-lang.org/tools/install). - Install PostgreSQL 15 (https://www.postgresql.org/download/) +- Install OpenSSL (used for TLS connections to the PostgreSQL backend: https://docs.rs/openssl/latest/openssl/#automatic) ### Building @@ -18,11 +19,12 @@ cargo build --release ### Running 1. **Edit Configuration**: Modify `./server/vss-server-config.toml` to set application configuration and - environment variables as needed. Add PostgreSQL endpoint configuration. -2. Create table in PostgreSQL using `./impls/src/postgres/sql/` + environment variables as needed. +2. VSS will setup a PostgreSQL database on first launch if it is not found. You can also manually create the database + using the statement at `./impls/src/postgres/sql/v0_create_vss_db.sql`. 3. Start server: ``` - cargo run -- server/vss-server-config.toml + cargo run server/vss-server-config.toml ``` 4. VSS endpoint should be reachable at `http://localhost:8080/vss`.