@p47h/vault-js 0.9.0

package/README.md

@@ -0,0 +1,150 @@
+# P47H Vault JS
+
+Secure, local-first cryptographic storage for browser environments.
+Backed by Argon2id, XChaCha20Poly1305, and Ed25519 via WebAssembly.
+
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](./LICENSE)
+[![Commercial License Available](https://img.shields.io/badge/Commercial-Available-green.svg)](https://p47h.com/licensing)
+
+## Overview
+
+P47H Vault JS addresses the insecurity of storing sensitive user secrets (API keys, private keys, PII) in browser storage mechanisms like `localStorage` or cookies.
+
+It provides an encrypted enclave within the client application, leveraging the P47H Core Rust implementation compiled to WebAssembly. This ensures that cryptographic operations are consistent across platforms and resistant to common JavaScript-based attack vectors.
+
+## Key Features
+
+* **WASM-Backed Cryptography:** Core logic resides in a compiled Rust binary, not interpreted JavaScript.
+* **Memory Isolation:** Private keys are generated within the WASM linear memory and are not exposed to the JavaScript heap as plain text during rest.
+* **Authenticated Encryption:** Data is persisted using XChaCha20Poly1305.
+* **Key Derivation:** Master keys are derived using Argon2id (OWASP recommendation) to resist brute-force attacks.
+* **Framework Agnostic:** Pure TypeScript implementation suitable for React, Vue, Angular, or vanilla JS.
+* **Dual Licensing:** AGPLv3 for open source, commercial licenses available for proprietary use.
+
+## Architecture
+
+This library adheres to Clean Architecture principles. It exposes a strict interface (`IVault`) and allows for dependency injection of storage adapters, ensuring testability and modularity.
+
+## Installation
+
+```bash
+npm install @p47h/vault-js
+```
+
+## Usage
+
+### Initialization (Open Source Mode)
+
+The library loads the WASM module asynchronously. By default, it runs in AGPLv3 mode:
+
+```typescript
+import { P47hVault } from '@p47h/vault-js';
+
+const vault = new P47hVault();
+await vault.init({ wasmPath: '/wasm/p47h_wasm_core_bg.wasm' });
+
+// Console will show: "🔓 P47H Vault: Running in AGPLv3 Mode..."
+```
+
+### Initialization (Commercial License)
+
+To activate a commercial license and remove the AGPLv3 nagware:
+
+```typescript
+import { P47hVault } from '@p47h/vault-js';
+
+const vault = new P47hVault();
+await vault.init({ 
+  wasmPath: '/wasm/p47h_wasm_core_bg.wasm',
+  licenseKey: 'YOUR_LICENSE_TOKEN_HERE'  // Format: PAYLOAD.SIGNATURE
+});
+
+// Check license status
+if (vault.isCommercialLicense()) {
+  console.log(`Licensed to: ${vault.getLicensee()}`);
+}
+```
+
+### Identity Creation
+
+Generates a new Ed25519 identity. The private key is encrypted immediately upon generation using a session key derived from the provided password.
+
+```typescript
+try {
+  const did = await vault.register("strong-user-password");
+  console.log("Identity created:", did); // e.g., did:p47h:123...
+} catch (error) {
+  console.error("Registration failed:", error);
+}
+```
+
+### Secure Storage
+
+Store arbitrary secrets. The payload is encrypted before touching the persistent storage layer.
+
+```typescript
+await vault.saveSecret("stripe_api_key", "sk_live_...");
+```
+
+### Zero-Exposure Usage
+
+Use stored secrets without extracting them to the application layer. The vault handles decryption and usage internally.
+
+```typescript
+// Example: Signing a payload with the identity's private key
+const signature = await vault.sign(new TextEncoder().encode("transaction_payload"));
+```
+
+## Licensing
+
+This project uses a **Dual Licensing** model with built-in IP protection ("Crypto-Nagware").
+
+### How It Works
+
+1. **Without License Key:** The SDK operates in AGPLv3 mode with visible console warnings reminding users of their obligation to release source code.
+
+2. **With Valid License Key:** The SDK verifies the Ed25519-signed license token embedded in the WASM binary. If valid, no warnings are shown.
+
+3. **Tamper Resistance:** The verification logic is compiled into Rust/WASM. Removing the nagware requires modifying and recompiling the source code, not just editing JavaScript.
+
+### Open Source License (AGPLv3)
+
+Free for use in open-source projects. If you integrate this library into an application, that application must also be released under the AGPLv3 license AND make source code available to network users.
+
+### Commercial License
+
+For proprietary, closed-source, or commercial applications, a commercial license is required. This license releases you from the copyleft requirements of the AGPLv3 and includes:
+
+* ✅ IP Indemnification
+* ✅ No AGPLv3 source disclosure requirements
+* ✅ No console nagware messages
+* ✅ Direct Support & Priority Updates
+* ✅ LTS Security Patches
+
+**[Get Your License](https://p47h.com/licensing)** | **[Contact Sales](mailto:support@p47h.com)**
+
+## API Reference
+
+### VaultConfig
+
+```typescript
+interface VaultConfig {
+  wasmPath?: string;      // Path to WASM binary (default: auto-detect)
+  storage?: IStorage;     // Custom storage adapter (default: IndexedDB)
+  licenseKey?: string;    // Commercial license token
+}
+```
+
+### License Methods
+
+```typescript
+// Check if commercial license is active
+vault.isCommercialLicense(): boolean;
+
+// Get licensee name (null if AGPLv3 mode)
+vault.getLicensee(): string | null;
+```
+
+---
+
+Copyright © 2026 P47H Team. All rights reserved.