secure-channel-sdk

A robust, high-performance SDK for Client-Side End-to-End Encryption (E2EE). Designed specifically for frontend-to-backend communication where the server acts as a "zero-knowledge" storage.

Key Features

• AES-GCM 256-bit: Industry-standard authenticated encryption.
• Hierarchical Key Derivation: Uses PBKDF2 (100,000 iterations) for passwords and HKDF for session-level security.
• Automatic Metadata Packaging: IVs, salts, and auth tags are automatically managed and packaged with your ciphertext.
• Context-Aware Security: Protects against "replay attacks" and "context-swapping" using AAD (Additional Authenticated Data).
• Universal: Seamlessly works in Browsers (Web Crypto API) and Node.js.

Installation

npm install secure-channel-sdk

Usage Guide

This SDK is designed for scenarios where User A encrypts a message that only User B (or User A at a later time) can decrypt, using a shared password or secret phrase.

1. Encrypting Data (Client-Side)

The PasswordChannel class handles everything. It generates unique salts and IVs for every encryption, ensuring that the same message encrypted twice results in different ciphertext.

import { PasswordChannel } from 'secure-channel-sdk';

const secretPhrase = 'your-secure-password';
const sensitiveData = 'This is a secret message for the backend.';

// 'Context' ensures the encrypted data is only valid for a specific scenario
const context = {
	method: 'POST',
	path: '/api/secure-message',
	userId: 'user_8832',
};

async function sendData() {
	const encryptedPkg = await PasswordChannel.encrypt(secretPhrase, sensitiveData, context);

	// Resulting encryptedPkg is a JSON object containing:
	// ctB64, tagB64, ivB64, saltB64, passwordSaltB64, etc.

	// Now send this entire object to your backend/recipient
	await fetch('/api/save', {
		method: 'POST',
		body: JSON.stringify(encryptedPkg),
	});
}

2. Decrypting Data

The recipient must provide the same password and the same context used during encryption. If a single bit of the data or context is altered, decryption will fail (preventing tampering).

import { PasswordChannel } from 'secure-channel-sdk';

async function receiveData(encryptedPkg) {
	try {
		const decrypted = await PasswordChannel.decrypt('your-secure-password', encryptedPkg, { method: 'POST', path: '/api/secure-message', userId: 'user_8832' });

		console.log('Decrypted result:', decrypted);
	} catch (error) {
		console.error('Decryption failed! Data might be tampered or password incorrect.');
	}
}

Security Architecture

1. Password Hardening: Your raw password is never used directly. It passes through PBKDF2 with a unique salt to create a Master Key.
2. Session Isolation: Using HKDF, the SDK derives a specific encryption key for every single message.
3. Integrity Checks: Unlike older methods (like AES-CBC), AES-GCM includes an authentication tag (tagB64). This guarantees the data hasn't been modified while sitting on the server.
4. Anti-Replay: Every message includes a sequence number (seq) and timestamp (ts) to prevent attackers from intercepting and re-sending old encrypted requests.

Performance

The SDK includes a built-in benchmark tool to ensure cryptographic operations don't block the main thread.

import { CryptoBenchmark } from 'secure-channel-sdk';

const stats = await CryptoBenchmark.run();
console.log(`Encryption speed: ${stats.speed256} MB/s`);

License

ISC © Mykola Dzoban