@pathscale/secure-local-storage-chacha20-poly1305 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-05-07
+
+### Changed
+- Switched encryption implementation from noble to `@stablelib/xchacha20poly1305`.
+- Replaced 12-byte ChaCha20-Poly1305 nonces with 24-byte XChaCha20-Poly1305 nonces.
+- Removed PBKDF2 key derivation; `hashKey` now expects a raw 32-byte key as hex, base64, or a 32-byte string.
+- Added a temporary built-in development key until auth provides the login-bound key.
+
+### Removed
+- Removed `@noble/ciphers` and `@noble/hashes`.
+
 ## [1.0.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -1,17 +1,16 @@
-# Secure Local Storage ChaCha20-Poly1305
+# Secure Local Storage XChaCha20-Poly1305
 
 [![npm](https://img.shields.io/npm/v/@pathscale/secure-local-storage-chacha20-poly1305.svg)](https://www.npmjs.com/package/@pathscale/secure-local-storage-chacha20-poly1305) [![downloads](https://img.shields.io/npm/dm/@pathscale/secure-local-storage-chacha20-poly1305.svg)](http://npm-stat.com/charts.html?package=@pathscale/secure-local-storage-chacha20-poly1305) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A secure, encrypted local storage library with browser fingerprinting for enhanced security. This fork provides a drop-in replacement for localStorage with ChaCha20-Poly1305 authenticated encryption, type preservation, and browser-specific security keys.
+A secure, encrypted local storage library. This fork provides a drop-in replacement for localStorage with XChaCha20-Poly1305 authenticated encryption and type preservation.
 
 ## 🚀 Features
 
-- **🔐 Automatic Encryption**: All data is encrypted using ChaCha20-Poly1305 with browser-specific keys
-- **🔍 Browser Fingerprinting**: Generates unique keys based on browser characteristics
+- **🔐 Automatic Encryption**: All data is encrypted using XChaCha20-Poly1305
 - **📝 Type Preservation**: Maintains original data types (string, number, boolean, object)
 - **🎯 Framework Agnostic**: Works with React, Vue, Angular, Vite, Next.js, and vanilla JavaScript
 - **💾 Memory Caching**: Singleton pattern with in-memory cache for performance
-- **🛡️ Secure by Default**: Each browser generates its own encryption key
+- **🛡️ Authenticated Encryption**: Stored values include an authentication tag
 - **⚙️ Configurable**: Extensive configuration options and environment variable support
 - **📦 TypeScript Ready**: Full TypeScript support with comprehensive type definitions
 - **🚀 Production Ready**: Thoroughly tested and optimized for performance
@@ -23,17 +22,14 @@ A secure, encrypted local storage library with browser fingerprinting for enhanc
 Regular localStorage stores data as plain text, making it vulnerable to:
 
 - **Data theft**: Anyone with device access can read your stored data
-- **Cross-browser attacks**: Encrypted data from one browser can be copied to another
+- **Tampering**: Stored ciphertext can be modified without the app noticing
 - **No type safety**: Everything is stored as strings, losing original data types
 
 ### The Solution
 
-Secure Local Storage generates a unique encryption key for each browser using:
-- Browser fingerprinting (10+ unique identifiers)
-- User-specific hash keys
-- Environment-specific configuration
-
-This ensures that data encrypted in one browser cannot be decrypted in another, even if the encrypted data is copied.
+Secure Local Storage encrypts values before writing them to localStorage. For now, the package uses
+a built-in 32-byte development key unless `hashKey` is provided as a raw 32-byte, base64, or hex key.
+This is intended to be replaced by an auth-provided key after login.
 
 ## 📦 Installation
 
@@ -91,9 +87,8 @@ import { SecureLocalStorage } from '@pathscale/secure-local-storage-chacha20-pol
 
 // Create a custom instance with configuration
 const customStorage = SecureLocalStorage.getInstance({
-  hashKey: 'my-custom-key',
+  hashKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
   prefix: 'myapp_',
-  disabledKeys: ['Canvas', 'Fonts'], // Disable specific fingerprint properties
   debug: true
 });
 
@@ -249,21 +244,11 @@ type FingerprintProperty =
 ## 🔒 Security Features
 
 ### Encryption Details
-- **Algorithm**: ChaCha20-Poly1305 authenticated encryption with PBKDF2-SHA256 key derivation
-- **Key Generation**: Combines user hash key with browser fingerprint
-- **Salt**: Uses a fixed salt for consistent key generation
-- **Iterations**: 1000 PBKDF2 iterations for key strengthening
-
-### Browser Fingerprinting
-The library generates a unique fingerprint using:
-- User agent string
-- Screen dimensions and color depth
-- Installed plugins
-- Available fonts (canvas-based detection)
-- Storage capabilities
-- Timezone and language settings
-- Canvas fingerprint
-- Current hostname
+- **Algorithm**: XChaCha20-Poly1305 authenticated encryption
+- **Implementation**: `@stablelib/xchacha20poly1305`
+- **Nonce**: 24-byte random nonce per encrypted value
+- **Key**: 32-byte raw key; accepts hex, base64, or raw 32-byte string input
+- **Temporary fallback**: Built-in development key until auth provides a login-bound key
 
 ### Data Protection
 - Each encrypted item includes metadata (type, timestamp, version)
@@ -395,9 +380,8 @@ If you have any questions or issues, please:
 
 ## 🔗 Related Projects
 
-- [noble-ciphers](https://github.com/paulmillr/noble-ciphers) - Audited JavaScript ciphers including ChaCha20-Poly1305
-- [fingerprintjs](https://github.com/fingerprintjs/fingerprintjs) - Browser fingerprinting
+- [StableLib](https://github.com/StableLib/stablelib) - TypeScript cryptography packages
 
 ---
 
-Forked from `@jahidulsaeid/secure-local-storage` and ported to ChaCha20-Poly1305.
+Forked from `@jahidulsaeid/secure-local-storage` and ported to XChaCha20-Poly1305.

package/dist/SecureLocalStorage.d.ts

@@ -4,7 +4,6 @@ import { SecureStorageConfig, StorageValue } from './types';
  */
 export declare class SecureLocalStorage {
     private static instance;
-    private fingerprinting;
     private encryption;
     private environment;
     private config;

package/dist/SecureLocalStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SecureLocalStorage.d.ts","sourceRoot":"","sources":["../src/SecureLocalStorage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAiB,MAAM,SAAS,CAAC;AAE3E;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,aAAa,CAAkB;IAEvC,OAAO;IA4BP;;OAEG;WACW,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,kBAAkB;IAOpF;;OAEG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAqBtD;;OAEG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY;IAoCzC;;OAEG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAmBpC;;OAEG;IACI,KAAK,IAAI,IAAI;IA+BpB;;OAEG;IACI,IAAI,IAAI,MAAM,EAAE;IAkBvB;;OAEG;IACI,MAAM,IAAI,MAAM;IAIvB;;OAEG;IACI,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAoBlE,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,qBAAqB;CAsB9B"}
+{"version":3,"file":"SecureLocalStorage.d.ts","sourceRoot":"","sources":["../src/SecureLocalStorage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAiB,MAAM,SAAS,CAAC;AAE3E;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,aAAa,CAAkB;IAEvC,OAAO;IA2BP;;OAEG;WACW,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,kBAAkB;IAOpF;;OAEG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAqBtD;;OAEG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY;IAoCzC;;OAEG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAmBpC;;OAEG;IACI,KAAK,IAAI,IAAI;IA+BpB;;OAEG;IACI,IAAI,IAAI,MAAM,EAAE;IAkBvB;;OAEG;IACI,MAAM,IAAI,MAAM;IAIvB;;OAEG;IACI,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAelE,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,qBAAqB;CAsB9B"}

package/dist/encryption.d.ts

@@ -7,7 +7,7 @@ export declare class EncryptionManager {
     private readonly version;
     private readonly textEncoder;
     private readonly textDecoder;
-    constructor(secretKey: string);
+    constructor(secretKey?: string);
     /**
      * Update the secret key
      */
@@ -24,7 +24,8 @@ export declare class EncryptionManager {
      * Validate if data was encrypted with this library
      */
     isValidEncryptedData(encryptedData: string): boolean;
-    private deriveKey;
+    private loadSecretKey;
+    private tryParseRawKey;
     private serializeData;
     private deserializeData;
     private getDataType;
@@ -32,5 +33,6 @@ export declare class EncryptionManager {
     private encodeBase64;
     private decodeBase64;
     private getGlobalBuffer;
+    private getRandomBytes;
 }
 //# sourceMappingURL=encryption.d.ts.map

package/dist/encryption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAwB,MAAM,SAAS,CAAC;AAuB7D;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,SAAS,EAAE,MAAM;IAI7B;;OAEG;IACI,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAKlD;;OAEG;IACI,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAsB1C;;OAEG;IACI,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY;IAoBnD;;OAEG;IACI,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO;IAe3D,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,eAAe;CAGxB"}
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAwB,MAAM,SAAS,CAAC;AA4B7D;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,SAAS,GAAE,MAAW;IAIlC;;OAEG;IACI,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAKlD;;OAEG;IACI,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAwB1C;;OAEG;IACI,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY;IAyBnD;;OAEG;IACI,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO;IAmB3D,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,cAAc;CAUvB"}