sevola-browser-sdk

v1.0.5

Published

4 months ago

Production-grade browser SDK for Sevola encryption services

0High
0Medium
0Low

kasfi_tamiya

sevola encryption crypto browser sdk aes pbkdf2 web-crypto

Sevola Browser SDK

A production-grade browser SDK for Sevola encryption services. Provides AES encryption/decryption with PBKDF2 key derivation, designed for modern web applications.

🚀 Features

AES-256-CBC Encryption with PBKDF2 key derivation
Web Crypto API support with fallback polyfills
Multiple key types: REST, Transit encryption
UMD/ESM module support
Browser compatibility with IE11+ support
TypeScript-friendly with JSDoc annotations
Production-ready with minified builds

📦 Installation

CDN (Recommended)

<!-- UMD build for direct browser use -->
<script src="https://unpkg.com/[email protected]/dist/sevola-sdk.umd.js"></script>

<!-- Minified version -->
<script src="https://unpkg.com/[email protected]/dist/sevola-sdk.min.js"></script>

<!-- Alternative: jsDelivr CDN -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/sevola-sdk.umd.js"></script>

NPM

npm install sevola-browser-sdk

Manual Download

Download the latest release from GitHub releases and include the appropriate file.

🔧 Usage

Vanilla HTML/JavaScript

<!DOCTYPE html>
<html>
<head>
    <title>Sevola SDK Test</title>
</head>
<body>
    <script src="https://unpkg.com/[email protected]/dist/sevola-sdk.umd.js"></script>
    <script>
        // Create client with API key
        const client = new SevolaSDK.EncryptClient('your-api-key-here');
        
        // Encrypt data
        async function encryptData() {
            try {
                const encrypted = await client.encryptData('Hello, World!');
                console.log('Encrypted:', encrypted);
            } catch (error) {
                console.error('Encryption failed:', error);
            }
        }
        
        // Decrypt data
        async function decryptData(encryptedData) {
            try {
                const decrypted = await client.decryptData(encryptedData);
                console.log('Decrypted:', decrypted);
            } catch (error) {
                console.error('Decryption failed:', error);
            }
        }
        
        // Test encryption
        encryptData();
    </script>
</body>
</html>

ES6 Modules

import { EncryptClient } from 'sevola-browser-sdk';

const client = new EncryptClient({
    apiKey: 'your-api-key-here',
    baseUrl: 'https://your-server.com',
    timeout: 30000
});

// Use the client
const encrypted = await client.encryptTransit('sensitive data');
const decrypted = await client.decryptTransit(encrypted);

// Dynamic transit encryption (each encryption gets a unique key)
const dynamicEncrypted = await client.encryptTransitDynamic('sensitive data');
const dynamicDecrypted = await client.decryptTransitDynamic(dynamicEncrypted);

Node.js (if needed)

const { EncryptClient } = require('sevola-browser-sdk');

const client = new EncryptClient('your-api-key-here');
// ... same usage as above

🏗️ API Reference

EncryptClient Constructor

new EncryptClient(options)

Parameters:

options (string|object): API key string or options object
- apiKey (string): Required - API key for authentication
- baseUrl (string): Base URL for key server (default: http://localhost:8082)
- timeout (number): Request timeout in ms (default: 30000)

Example:

// Simple constructor with API key
const client = new EncryptClient('your-api-key');

// Full options constructor
const client = new EncryptClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://api.sevola.com',
    timeout: 60000
});

Core Methods

`encryptData(plaintext)`

Encrypt data using REST key.

Parameters:

plaintext (string): Text to encrypt

Returns: Promise - Base64 encoded encrypted data

`decryptData(ciphertext)`

Decrypt data using REST key.

Parameters:

ciphertext (string): Base64 encoded encrypted data

Returns: Promise - Decrypted plaintext

`encryptTransit(plaintext)`

Encrypt data using transit key.

Parameters:

plaintext (string): Text to encrypt

Returns: Promise - Base64 encoded encrypted data

`decryptTransit(ciphertext)`

Decrypt data using transit key.

Parameters:

ciphertext (string): Base64 encoded encrypted data

Returns: Promise - Decrypted plaintext

`encryptTransitDynamic(plaintext)`

Encrypt data using dynamic transit key. Each encryption gets a unique key with trace ID.

Parameters:

plaintext (string): Text to encrypt

Returns: Promise - Base64 encoded encrypted data with trace ID

Example:

// Encrypt with dynamic transit key
const encrypted = await client.encryptTransitDynamic('sensitive data');
// Result: "encryptedDatax-sevola-traceid=abc123..."

`decryptTransitDynamic(ciphertext)`

Decrypt data using dynamic transit key. Automatically extracts trace ID to fetch the correct key.

Parameters:

ciphertext (string): Base64 encoded encrypted data with trace ID

Returns: Promise - Decrypted plaintext

Example:

// Decrypt with dynamic transit key
const decrypted = await client.decryptTransitDynamic(encrypted);
// Automatically handles trace ID extraction and key fetching

Utility Methods

`isReady()`

Check if the client is properly configured.

Returns: boolean - True if client is ready

`getConfig()`

Get client configuration.

Returns: object - Client configuration object

SevolaSDK Global Object

`SevolaSDK.createClient(options)`

Factory method to create new client instances.

`SevolaSDK.isSupported()`

Check if the current environment supports all required features.

`SevolaSDK.getMissingFeatures()`

Get list of missing features in the current environment.

🔐 Encryption Details

Algorithm Specifications

Encryption: AES-256-CBC
Key Derivation: PBKDF2 with SHA-256
Iterations: 1000
Salt: Fixed salt "FixedSalt123456"
IV: Random 16-byte IV for each encryption

Key Management

The SDK automatically fetches encryption keys from the configured key server:

REST Keys: For general data encryption
Transit Keys: For transport layer encryption

Keys are fetched securely and decrypted using your API key before use.

🌐 Browser Support

| Browser | Version | Support | |---------|---------|---------| | Chrome | 60+ | ✅ Full | | Firefox | 55+ | ✅ Full | | Safari | 11+ | ✅ Full | | Edge | 79+ | ✅ Full | | IE11 | 11+ | ⚠️ Limited |

Polyfills

The SDK includes automatic polyfills for:

Web Crypto API
TextEncoder/TextDecoder
ArrayBuffer utilities

📝 Examples

Complete Working Example

<!DOCTYPE html>
<html>
<head>
    <title>Sevola SDK Complete Example</title>
    <style>
        body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }
        .result { background: #f5f5f5; padding: 10px; margin: 10px 0; border-radius: 4px; }
        .error { background: #ffebee; color: #c62828; }
        .success { background: #e8f5e8; color: #2e7d32; }
    </style>
</head>
<body>
    <h1>Sevola SDK Test</h1>
    
    <div>
        <label>API Key:</label><br>
        <input type="text" id="apiKey" placeholder="Enter your API key" style="width: 300px;"><br><br>
        
        <label>Data to Encrypt:</label><br>
        <input type="text" id="dataInput" value="Hello, Sevola!" style="width: 300px;"><br><br>
        
        <button onclick="testEncryption()">Test Encryption</button>
        <button onclick="testTransit()">Test Transit</button>
        <button onclick="testDynamicTransit()">Test Dynamic Transit</button>
    </div>
    
    <div id="results"></div>
    
    <script src="https://unpkg.com/[email protected]/dist/sevola-sdk.umd.js"></script>
    <script>
        function showResult(message, isError = false) {
            const results = document.getElementById('results');
            const div = document.createElement('div');
            div.className = `result ${isError ? 'error' : 'success'}`;
            div.textContent = message;
            results.appendChild(div);
        }
        
        async function testEncryption() {
            try {
                const apiKey = document.getElementById('apiKey').value;
                const data = document.getElementById('dataInput').value;
                
                if (!apiKey) {
                    showResult('Please enter an API key', true);
                    return;
                }
                
                const client = new SevolaSDK.EncryptClient(apiKey);
                const encrypted = await client.encryptData(data);
                const decrypted = await client.decryptData(encrypted);
                
                showResult(`✅ Encryption successful!\nOriginal: ${data}\nEncrypted: ${encrypted}\nDecrypted: ${decrypted}`);
            } catch (error) {
                showResult(`❌ Error: ${error.message}`, true);
            }
        }
        
        async function testTransit() {
            try {
                const apiKey = document.getElementById('apiKey').value;
                const data = document.getElementById('dataInput').value;
                
                if (!apiKey) {
                    showResult('Please enter an API key', true);
                    return;
                }
                
                const client = new SevolaSDK.EncryptClient(apiKey);
                const encrypted = await client.encryptTransit(data);
                const decrypted = await client.decryptTransit(encrypted);
                
                showResult(`✅ Transit encryption successful!\nOriginal: ${data}\nEncrypted: ${encrypted}\nDecrypted: ${decrypted}`);
            } catch (error) {
                showResult(`❌ Error: ${error.message}`, true);
            }
        }
        
        async function testDynamicTransit() {
            try {
                const apiKey = document.getElementById('apiKey').value;
                const data = document.getElementById('dataInput').value;
                
                if (!apiKey) {
                    showResult('Please enter an API key', true);
                    return;
                }
                
                const client = new SevolaSDK.EncryptClient(apiKey);
                const encrypted = await client.encryptTransitDynamic(data);
                const decrypted = await client.decryptTransitDynamic(encrypted);
                
                showResult(`✅ Dynamic Transit encryption successful!\nOriginal: ${data}\nEncrypted: ${encrypted}\nDecrypted: ${decrypted}`);
            } catch (error) {
                showResult(`❌ Error: ${error.message}`, true);
            }
        }
    </script>
</body>
</html>

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔄 Changelog

v1.0.1

Added dynamic transit encryption/decryption support
Added encryptTransitDynamic() and decryptTransitDynamic() methods
Added trace ID handling for dynamic keys
Enhanced API documentation with practical examples

v1.0.0

Initial release
AES-256-CBC encryption with PBKDF2
REST and Transit key support
Browser polyfills
UMD/ESM module support

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Sevola Browser SDK

🚀 Features

📦 Installation

CDN (Recommended)

NPM

Manual Download

🔧 Usage

Vanilla HTML/JavaScript

ES6 Modules

Node.js (if needed)

🏗️ API Reference

EncryptClient Constructor

Core Methods

encryptData(plaintext)

decryptData(ciphertext)

encryptTransit(plaintext)

decryptTransit(ciphertext)

encryptTransitDynamic(plaintext)

decryptTransitDynamic(ciphertext)

Utility Methods

isReady()

getConfig()

SevolaSDK Global Object

SevolaSDK.createClient(options)

SevolaSDK.isSupported()

SevolaSDK.getMissingFeatures()

🔐 Encryption Details

Algorithm Specifications

Key Management

🌐 Browser Support

Polyfills

📝 Examples

Complete Working Example

🤝 Contributing

📄 License

🔄 Changelog

v1.0.1

v1.0.0

`encryptData(plaintext)`

`decryptData(ciphertext)`

`encryptTransit(plaintext)`

`decryptTransit(ciphertext)`

`encryptTransitDynamic(plaintext)`

`decryptTransitDynamic(ciphertext)`

`isReady()`

`getConfig()`

`SevolaSDK.createClient(options)`

`SevolaSDK.isSupported()`

`SevolaSDK.getMissingFeatures()`