velox-database

Breaking Changes in v1.0.3

IMPORTANT: This version removes default encryption key for security reasons.

• encryptionKey is now REQUIRED in configuration
• Database files created with v1.0.2 or earlier CANNOT be opened with v1.0.3 without the original encryption key
• You must provide your own strong encryption key (minimum 32 characters recommended)
• No more hardcoded or default keys - your data is truly secure

Migration Guide:

// OLD (v1.0.2) - WORKED WITH DEFAULT KEY
const db = new VeloxDB('./my-database');

// NEW (v1.0.3) - REQUIRES ENCRYPTION KEY
const db = new VeloxDB({
    path: './my-database',
    encryptionKey: 'your-strong-encryption-key-min-32-chars-long!!'
});

Table of Contents

· What is VeloxDB? · Features · Installation · Quick Start · CLI Usage · Multi-Language Support · API Reference · Binary Format · Security Features · Encryption · Usage Examples · FAQ · Terms of Service · License

What is VeloxDB?

VeloxDB is a high-performance embedded key-value database with zero-configuration storage, atomic writes, and military-grade encryption. Unlike traditional databases that store data as readable JSON or text, VeloxDB uses AES-256-GCM or ChaCha20-Poly1305 encryption combined with a proprietary binary format that is compact, fast to parse, and completely unreadable without the correct encryption key.

VeloxDB is designed for:

· Embedded systems and edge computing · High-throughput caching layers · Session and OTP storage with automatic expiration · Lightweight local databases for desktop/mobile apps · Serverless and microservice architectures · Applications requiring data-at-rest encryption

Features

Category Features Storage Engine Binary format, Zero-config, Write-Ahead Log (WAL), Atomic writes, Compaction, Snapshots Performance In-memory LRU cache, Primary key indexing, Buffer API, Async I/O Security AES-256-GCM encryption, ChaCha20-Poly1305 encryption, XOR obfuscation, Whitelist/Blacklist IP, Rate limiting, Authentication tokens, Ghost mode Data Types String, Integer, Object (JSON), Buffer, Link (pointer), Null TTL Automatic expiration, TTL inspection, Expire command Transactions ACID-like, Begin/Commit/Rollback, Preview changes CLI Interactive shell, Real-time monitoring (top), Benchmarking, Snapshot management, Firewall control Multi-Language JavaScript/TypeScript (Native), PHP, Kotlin, Java, C++, Express.js integration

Installation

From NPM

npm install velox-database
npm install -g velox-database

Requirements

Requirement Minimum Recommended Node.js 18.0.0 20.0.0+ RAM 128 MB 512 MB+ Storage 50 MB 1 GB+ OS Linux 5.4+ Ubuntu 22.04+

Quick Start

JavaScript / TypeScript

const { VeloxDB } = require('velox-database');

async function main() {
  // REQUIRED: Provide your own encryption key (min 32 characters)
  const db = new VeloxDB({
    path: './my-database',
    encryptionKey: 'my-very-strong-secret-key-min-32-chars-long!!'
  });
  
  // First time setup - register user
  await db.register('admin', 'password123', '127.0.0.1');
  
  // Login
  const login = await db.login('admin', 'password123', '127.0.0.1');
  console.log(login.message);
  
  if (login.success) {
    // Set data
    await db.set('user:1', { name: 'Dimas', role: 'Developer' });
    await db.set('counter', 100);
    await db.set('session:abc', { token: 'xyz' }, { ttl: 3600 });
    
    // Get data
    const user = await db.get('user:1');
    console.log('User:', user);
    
    // Check existence
    const exists = await db.has('user:1');
    console.log('Exists:', exists);
    
    // Delete data
    await db.delete('user:1');
    
    // Create link (pointer)
    await db.link('alias:user', 'user:1');
    
    // Get stats
    console.log('Stats:', db.getStats());
  }
  
  await db.close();
}

main();

Using CLI

# Start interactive CLI
velox-database --cli

# Inside CLI after login:
velox> set user:1 {"name":"Dimas","role":"Dev"}
velox> get user:1
velox> ls
velox> stats
velox> top
velox> shrink
velox> snapshot create backup1
velox> exit

CLI Usage

Basic Commands

# Start CLI mode
velox-database --cli

# Decode database to plain text (requires encryption key)
velox-database --decode -i ./veloxdb_data/data.veloxdb --encryption-key "your-key" --pretty

# Decode to JSON file
velox-database --decode -i ./veloxdb_data/data.veloxdb --encryption-key "your-key" -o data.json --pretty

# Inspect specific key (hex dump)
velox-database --decode -i ./veloxdb_data/data.veloxdb --encryption-key "your-key" -x user:1

# Real-time monitoring
velox-database --monitor

Interactive CLI Commands

Command Description set Store value (JSON, string, number) get Retrieve value del Delete key has Check existence expire Set expiration ttl Get remaining TTL link Create pointer link inspect Show binary hex dump ls [prefix] List keys cd Change namespace prefix stats Show database statistics top Real-time monitoring shrink Run compaction with animation compact Run compaction snapshot create Create snapshot snapshot restore Restore snapshot snapshot list List snapshots begin Start transaction commit Commit transaction rollback Rollback transaction whoami Show current user info audit Show access logs firewall add Whitelist IP firewall block Blacklist IP limit set Set rate limit ghost on Enable ghost mode flushdb --force Delete all data exit Quit CLI

API Reference

VeloxDB Class

const { VeloxDB } = require('velox-database');

Constructor

const db = new VeloxDB(config);

Parameter Type Description config object Configuration object (required) config.path string Database directory path config.encryptionKey string REQUIRED - Your encryption key (min 32 chars) config.cacheSize number LRU cache size in items (default: 1000) config.xorKey number XOR key for additional obfuscation (default: 0xAC) config.enableObfuscation boolean Enable XOR obfuscation (default: true) config.encryptionAlgorithm string 'aes-256-gcm' or 'chacha20-poly1305' (default: 'aes-256-gcm')

Authentication Methods

Method Description register(username, password, ip) Register new user login(username, password, ip) Login and get token logout() Logout current user hasUsers() Check if any users exist whoami() Get current user info

Data Methods

Method Description set(key, value, options) Store value (auto-detect type) get(key, ghostSecret?) Retrieve value delete(key) Delete key has(key) Check existence expire(key, seconds) Set TTL on existing key ttl(key) Get remaining TTL in seconds link(alias, target) Create pointer link inspect(key) Get binary hex dump

Transaction Methods

Method Description transaction() Create new transaction transaction().set(key, value) Stage set operation transaction().delete(key) Stage delete operation transaction().commit() Commit transaction transaction().rollback() Cancel transaction

Maintenance Methods

Method Description compact() Run compaction, return size saved createSnapshot(name?) Create snapshot restoreSnapshot(name) Restore snapshot listSnapshots() List all snapshots flushAll() Delete all data getStats() Get database statistics getTopKeys(limit) Get most accessed keys ls(prefix?) List all keys cd(prefix) Filter keys by prefix

Security Methods

Method Description enableGhostMode(secret) Enable ghost mode (returns null unless secret provided) disableGhostMode() Disable ghost mode whitelistIp(ip) Add IP to whitelist blacklistIp(ip) Block IP setGlobalRateLimit(limit) Set requests per second limit getFirewall() Get firewall instance getRateLimiterStats() Get rate limiter statistics

Binary Format

VeloxDB uses a proprietary binary format for efficient storage and fast parsing.

Format Structure

+----------+-----------+-----------+----------+-------------+-------+-----------+----------+
| MAGIC    | KEY LEN   | KEY       | TYPE     | VALUE LEN   | VALUE | TIMESTAMP | DELIM    |
| (2 bytes)| (4 bytes) | (N bytes) | (1 byte) | (4 bytes)   | (M bytes)| (8 bytes)| (5 bytes)|
+----------+-----------+-----------+----------+-------------+-------+-----------+----------+

Magic Bytes: 0x56 0x4C ("VL")

Data Types:

· 0x00 - NULL · 0x01 - String · 0x02 - Integer (64-bit) · 0x03 - Object (JSON) · 0x04 - Buffer · 0x05 - Link (pointer)

Delimiter: 0x00 0x00 0x7E 0x00 0x00

Encryption

VeloxDB uses strong encryption to protect your data at rest.

Encryption Layers

1. AES-256-GCM or ChaCha20-Poly1305 (Primary) · Military-grade encryption · Authentication tag prevents tampering · PBKDF2 key derivation with 100,000 iterations
2. XOR Obfuscation (Secondary) · Additional layer of protection · Makes encrypted data look like random garbage

Encryption Flow

Original Data → AES-256-GCM/ChaCha20-Poly1305 → XOR 0xAC → .veloxdb file

Decryption Flow

.veloxdb file → XOR 0xAC → AES-256-GCM/ChaCha20-Poly1305 → Original Data

Security Components

· Salt (32 bytes) - Prevents rainbow table attacks · IV (16 bytes) - Unique initialization vector per encryption · Auth Tag (16 bytes) - Verifies data integrity · PBKDF2 - Key derivation with 100,000 iterations · SHA256 - Hash for key derivation

Choosing an Encryption Algorithm

Algorithm Speed Security Best For AES-256-GCM Fast Very High General purpose, hardware acceleration ChaCha20-Poly1305 Very Fast Very High Devices without AES hardware

Security Features

Authentication System

VeloxDB includes a complete authentication system with:

· Password hashing (SHA-256) · Session tokens (32-byte random) · Token expiration (default 1 hour) · Persistent user storage

Rate Limiting

· Login attempts: 5 per minute, 5 minute block after exceeded · Registration attempts: 3 per hour, 24 hour block after exceeded · Global request limit: Configurable (default 100 req/sec)

Firewall

· IP whitelist / blacklist · Access logging with timestamps · Failed attempt tracking

Ghost Mode

When enabled, all get() operations return null unless a secret key is provided. This provides an additional layer of obfuscation for sensitive data.

Usage Examples

Basic CRUD Operations

const { VeloxDB } = require('velox-database');

async function example() {
  const db = new VeloxDB({
    path: './data',
    encryptionKey: 'your-strong-key-min-32-chars!!'
  });
  
  await db.register('user', 'pass', '127.0.0.1');
  await db.login('user', 'pass', '127.0.0.1');
  
  // Set different data types
  await db.set('string:key', 'hello world');
  await db.set('number:key', 42);
  await db.set('object:key', { name: 'John', age: 30 });
  await db.set('buffer:key', Buffer.from('binary data'));
  
  // Get with type preservation
  const str = await db.get('string:key');  // Returns string
  const num = await db.get('number:key');  // Returns number
  const obj = await db.get('object:key');  // Returns object
  
  // Set with TTL (auto-expire after 60 seconds)
  await db.set('session:temp', { id: 123 }, { ttl: 60 });
  
  // Check TTL remaining
  const remaining = await db.ttl('session:temp');
  console.log(`Expires in ${remaining} seconds`);
  
  await db.close();
}

Using Environment Variable for Encryption Key

// .env file
// VELOXDB_ENCRYPTION_KEY=your-strong-encryption-key-min-32-chars-long

const { VeloxDB } = require('velox-database');

async function example() {
  const db = new VeloxDB({
    path: './data',
    encryptionKey: process.env.VELOXDB_ENCRYPTION_KEY
  });
  
  await db.register('admin', 'password123', '127.0.0.1');
  await db.login('admin', 'password123', '127.0.0.1');
  
  await db.set('secret', 'encrypted data');
  console.log(await db.get('secret'));
  
  await db.close();
}

Transaction Example

async function transactionExample() {
  const db = new VeloxDB({
    path: './data',
    encryptionKey: 'your-strong-encryption-key-min-32-chars-long!!'
  });
  
  await db.login('user', 'pass', '127.0.0.1');
  
  const txn = db.transaction();
  
  txn.set('account:1', { balance: 1000 });
  txn.set('account:2', { balance: 500 });
  txn.link('primary:account', 'account:1');
  
  console.log('Preview:', txn.getPreview('account:1'));
  
  await txn.commit();
  
  await db.close();
}

Security Configuration

async function securityExample() {
  const db = new VeloxDB({
    path: './data',
    encryptionKey: 'your-strong-encryption-key-min-32-chars-long!!',
    encryptionAlgorithm: 'chacha20-poly1305'  // Use ChaCha20 for better performance
  });
  
  db.setGlobalRateLimit(50);
  db.whitelistIp('192.168.1.100');
  db.blacklistIp('45.33.22.11');
  
  await db.enableGhostMode('my-super-secret-key');
  
  const hidden = await db.get('secret:data'); // null
  const revealed = await db.get('secret:data', 'my-super-secret-key');
  
  const firewall = db.getFirewall();
  const logs = firewall.getAccessLogs(10);
  console.log('Recent access:', logs);
  
  await db.close();
}

FAQ

Q1: What happens if I lose my encryption key?

Answer: The data is irrecoverable. There is no backdoor or default key. This is by design for security. Keep your encryption key safe in environment variables or a secure key management system.

Q2: Can I change the encryption key after creating a database?

Answer: No, the encryption key is tied to the database file. To change the key, you would need to decrypt the data with the old key and re-encrypt with the new key using a migration script.

Q3: Is the encryption key stored anywhere?

Answer: No. VeloxDB never stores your encryption key. You must provide it each time you open the database. The key is only used in memory for encryption/decryption operations.

Q4: How is the encryption key used?

Answer: The key is passed through PBKDF2 with a random salt (100,000 iterations) to derive the actual encryption key. This prevents brute-force attacks and rainbow table lookups.

Q5: What's the performance impact of encryption?

Answer: AES-256-GCM adds approximately 10-20% overhead. ChaCha20-Poly1305 is slightly faster on devices without AES hardware acceleration. The binary format and XOR obfuscation add minimal overhead.

Q6: Can I disable encryption for development?

Answer: No. For security reasons, encryption is required. For development, use a test encryption key stored in environment variables.

Q7: Is the database file secure if someone steals it?

Answer: Yes. Without the correct encryption key, the data is completely unreadable. The combination of AES-256-GCM (or ChaCha20-Poly1305) plus XOR obfuscation makes brute-force attacks computationally infeasible.

Q8: What is the difference between encryption and XOR obfuscation?

Answer: XOR obfuscation is a simple bitwise operation that prevents casual viewing but can be easily reversed. Encryption (AES-256-GCM/ChaCha20-Poly1305) is cryptographically secure and cannot be broken without the key.

Terms of Service

Please read these Terms of Service carefully before using VeloxDB.

1. Acceptance of Terms

By downloading, installing, or using VeloxDB (the "Software"), you agree to be bound by these Terms of Service.

2. Intended Use

VeloxDB is designed for legitimate purposes including:

· Storing and retrieving data for your own applications · Caching frequently accessed data · Session and token management · Local data persistence for desktop/mobile apps · Edge computing and IoT data storage · Prototyping and development

3. Prohibited Uses

You agree NOT to use VeloxDB for:

· Storing illegal content · Processing sensitive personal data without proper consent · Any activity that violates data protection laws · Bypassing security measures of other systems · Building malware or harmful software

4. Responsibility and Liability

THE AUTHOR PROVIDES THIS SOFTWARE "AS IS" WITHOUT WARRANTIES. YOU ARE RESPONSIBLE FOR SAFEGUARDING YOUR ENCRYPTION KEYS. LOST KEYS RESULT IN PERMANENT DATA LOSS.

5. No Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

6. Limitations of Liability

IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DAMAGES ARISING FROM THE USE OF THIS SOFTWARE.

7. Ethical Reminder

Use this tool responsibly. Respect user privacy, follow data protection laws, and don't use this for harmful purposes.

License

MIT License

Copyright (c) 2026 Dimzxzzx07

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.