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

``bash
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.

$3

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.

`typescript
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),
});
}
`

$3

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).

`typescript
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.

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

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

License

ISC © Mykola Dzoban