▶️Getting Started

VSS API Client

The VSS API Client is a Node.js utility designed to interact with a Versioned Storage Service (VSS). It provides functionality to securely store, retrieve, and manage encrypted data using a cloud-hosted VSS server. Client code

Features

  • File Storage: Encrypt and upload files to the VSS server.

  • File Retrieval: Decrypt and fetch files from the server.

  • Key Version Management: List versions of stored keys for audit and recovery purposes.

  • Client-Side Encryption: Ensures data is encrypted locally using AES-256-GCM before being transmitted.

  • Protobuf Serialization: Leverages Protobuf for efficient data communication.

Prerequisites

  1. VSS Server: Access to a running VSS server instance. https://safe.thunderstack.org/vss

  2. Protobuf Schema: Obtain the vss.proto file from the VSS service provider.

Installation

  1. Clone the repository:

    git clone https://github.com/RGB-OS/vss-server
cd https://github.com/RGB-OS/vss-server/nodejs-api-client

  2. Install dependencies:

    npm install

  3. Configure the client:

    • Update config.js with:

      • token: JWT token for authentication.

      • vssServerBaseUrl: Base URL for the VSS server.

      • ENCRYPTION_KEY: 32-byte AES encryption key in Base64 format.

Usage

1. Save a File

Upload a file to the VSS server:

const { putObjects } = require('./client');

async function saveFile() {
    const filePath = 'example.txt';
    const storeId = 'store_example';
    const key = 'file_key';

    const response = await putObjects(filePath, storeId, key);
    console.log('File stored successfully:', response.data);
}

saveFile();

2. Retrieve a File

Fetch and decrypt a file from the VSS server:

const { getObject } = require('./client');

async function fetchFile() {
    const storeId = 'store_example';
    const key = 'file_key';

    const content = await getObject(storeId, key);
    console.log('Decrypted Content:', content);
}

fetchFile();

3. List Key Versions

Retrieve a list of versions for a specific key:

const { listKeyVersions } = require('./client');

async function listVersions() {
    const storeId = 'store_example';

    const versions = await listKeyVersions(storeId);
    console.log('Key Versions:', versions);
}

listVersions();

Configuration

config.js Example

module.exports = {
    token: '<JWT_TOKEN>', // Replace with your JWT token
    vssServerBaseUrl: 'https://safe.thunderstack.org/vss', // or Replace with your VSS server base URL
    ENCRYPTION_KEY: Buffer.from('<BASE64_ENCRYPTION_KEY>', 'base64') // Replace with a valid 32-byte encryption key
};

Generate an AES-256 Encryption Key

Run the following command to generate a 32-byte key:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'));"

Directory Structure

.
├── client.js            # Main API client
├── encryptor.js         # Encryption and decryption utilities
├── protobufUtils.js     # Protobuf schema loader
├── config.js            # Configuration file
├── vss.proto            # Protobuf schema for VSS requests
└── README.md            # Documentation

Security

  • Client-Side Encryption: Data is encrypted locally using AES-256-GCM before being sent to the server.

Troubleshooting

Common Issues

  1. Invalid Token:

    • Ensure the token in config.js is valid and not expired.

  2. Connection Errors:

    • Verify the vssServerBaseUrl is correct and the server is running.

  3. Encryption Errors:

    • Ensure the ENCRYPTION_KEY meets format and length requirements.

Contact

For questions or support, reach out to [email protected].

PreviousFeaturesNext🔗 ThunderLink

Last updated