local-first-privacy-encryption-sdk

Local-First Privacy & Encryption SDK

Zero-dependency Web Crypto envelope encryption, PBKDF2 portable archives, and client-side private search.

---

1. WHAT IS THIS?

The Local-First Privacy & Encryption SDK is a zero-dependency JavaScript/TypeScript library for web applications, browser extensions, and local-first software. It provides client-side envelope encryption (AES-GCM-256 with AES-KW key wrapping), passphrase-derived encrypted portable archives (PBKDF2-600,000 with SHA-256), and in-memory full-text search that executes entirely on the client without transmitting plaintext to backend servers.

2. WHO IS IT FOR?

• SaaS & Web3 Builders: Implementing end-to-end encryption (E2EE) where server infrastructure stores only ciphertext.
• Healthcare, Legal & FinTech Developers: Managing sensitive records subject to data sovereignty, minimization, and privacy compliance.
• Local-First Application Architects: Building offline-capable apps with secure local storage and backup exports.

3. WHAT PROBLEM DOES IT SOLVE?

Storing plaintext user data on centralized servers exposes businesses to catastrophic data breaches, subpoena exposure, and massive regulatory liability. Naive client-side encryption libraries frequently suffer from dependency bloat, vulnerable third-party cryptographic primitives, missing Additional Authenticated Data (AAD) binding, and insecure server-dependent search architectures.

4. WHY PAY FOR IT INSTEAD OF BUILDING IT?

• Native Web Crypto Standards: Uses native W3C Web Cryptography API (crypto.subtle) available in modern browsers and Node.js 18+, eliminating third-party JS crypto attack surfaces.
• Cryptographic Envelope Architecture: Encrypts records with ephemeral 256-bit AES-GCM data encryption keys (DEKs), wrapped with 256-bit AES-KW key encryption keys (KEKs) derived from a 32-byte root key via HKDF-SHA256.
• Explicit AAD Tenant Binding: Cryptographically binds tenant ID, record ID, and revision ID into the AEAD authentication tag to prevent ciphertext transplantation attacks.
• Hardened Portable Backup Archives: Exports state into self-contained JSON archives protected by PBKDF2-SHA256 (600,000 iterations default) with high-entropy salts.
• Zero-Leakage Local Search: Indexes and ranks decrypted documents locally using an in-memory TF-IDF/BM25-style scorer without sending search queries to any remote server.
• Zero External Dependencies: Built 100% on standard platform runtime APIs.

5. WHAT IS VERIFIED?

• 9 / 9 Automated Unit Tests Passed: Roundtrip envelope encryption/decryption, ciphertext tampering rejection, PBKDF2 archive roundtrip, passphrase length and wrong passphrase rejection, client-side private search ranking, buffer zeroization, wrong root key rejection, tampered AAD rejection, and empty search edge cases.
• Clean-Environment Isolation: 100% pass in an isolated temporary environment with zero external dependencies.

6. HOW DO I RUN IT?

# 1. Run unit test suite
node --test tests/crypto-privacy.test.mjs

# 2. Run interactive encryption and search demonstration
node examples/demo.mjs