V1.0.4
This version focuses on replacing secure-ls which uses crypto-js <4.2.0 PBKDF2 (1.3M times weaker than current standard).
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,24 +1,66 @@ | ||
| ## Reactive LocalStorage for React | ||
|
|
||
| Reactive LocalStorage for React that uses [secure-ls](https://github.com/softvar/secure-ls) underneath for encryption. | ||
| <div align="center"> | ||
| <h3>Reactive LocalStorage for React</h3> | ||
| <br /> | ||
| </div> | ||
|
|
||
| Reactive LocalStorage for React that uses [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) underneath for encryption using AES-GCM. | ||
|
|
||
|
|
||
| ### Table of Contents | ||
| - [Browser Support](#browser-support) | ||
| - [Installation](#installation) | ||
| - [API](#api) | ||
| - [Usage](#usage) | ||
| - [Encryption](#encryption) | ||
| - [Disabling Encryption](#disabling-encryption) | ||
|
|
||
|
|
||
| ### Browser Support | ||
|  |  |  |  |  | | ||
| --- | --- | --- | --- | --- | | ||
| Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | | ||
|
|
||
|
|
||
| ### Installation | ||
| ``` | ||
| ```bash | ||
| $ pnpm i react-reactive-storage | ||
| ``` | ||
|
|
||
| ### API | ||
| It provides an easy-to-use `useLsState` hook which is very similar to `useState` in react. An additional `key` parameter is used which defines key of object on local storage. | ||
|
|
||
| ``` | ||
| ```ts | ||
| const [state, setState] = useLsState<T>(key: string, defaultValue?: T); | ||
| ``` | ||
|
|
||
| ### Usage | ||
| The usage is similar to `useState` from React with an | ||
| ``` | ||
| The usage is similar to `useState` from React. | ||
| ```ts | ||
| import { useLsState } from "react-reactive-storage"; | ||
|
|
||
| const [user, setUser] = useLsState<{name: string, age: number}>('user', {name: 'asad', age: 2}); | ||
| ``` | ||
| The item in localstorage is fully reactive and is updated and reflected everywhere even when changed through multiple tabs, either by 'setState' method or any other means for example through `window.localstorage` or devtools. | ||
|
|
||
| The item in localstorage is fully reactive and is updated and reflected everywhere even when changed through multiple tabs, either by 'setState' method or any other means for example through `window.localstorage` or devtools. | ||
| Note that if encryption is enabled (see below) and the encrypted data is changed by any other means than this library, it will corrupt the data and value will be read null. See below for more details. | ||
|
|
||
|
|
||
| ### Encryption | ||
| **Important**: Sensitive secrets should never be stored on client-side even in encrypted format. | ||
|
|
||
| The encryption is done through Web Crypto API which is native in Javascript that provides cryptographic functions under CryptoSubtle interface. | ||
|
|
||
| The library uses `AES_GCM` algorithm. First it generates a symmetric key, encrypts the key further using a wrapping key and stores it in local storage with name `secure_reactive_storage` to persist the key across reloads. | ||
| If `secure_reactive_storage` already exists in local storage then it decrypts the key and use it for encryption/decryption. | ||
| Whenever data is read/written, the data is encrypted/decrypted using this symmetric key. | ||
| If `secure_reactive_storage` gets deleted or modified, the key will be failed to load on page load and a new key will be generated hence discarding all the data encrypted with that key. | ||
|
|
||
| ##### Disabling Encryption | ||
| By default encryption is **enabled**. The encryption can be enabled/disabled through `ReactiveStorage` class using `disableEncryption` method. Call the function once in the entry point of your app (e.g. in `main.tsx` or `App.tsx` whatever you have). | ||
|
|
||
| ```ts | ||
| import { ReactiveStorage } from 'react-reactive-storage' | ||
|
|
||
| ReactiveStorage.disableEncryption(true); | ||
| ``` |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| export abstract class ReactiveStorage { | ||
| static #encrypted = true; | ||
|
|
||
| static disableEncryption(value: boolean) { | ||
| this.#encrypted = !value; | ||
| } | ||
|
|
||
| static isEncrypted() { return this.#encrypted; } | ||
| } | ||
|
|
||
| class Crypto { | ||
|
|
||
| #key: CryptoKey | null; | ||
| enc = new TextEncoder(); | ||
| dec = new TextDecoder(); | ||
|
|
||
| static #iv = new Uint8Array([-26, 100, -118, -90, -29, 56, 24, -66, -18, -107, -24, 109, -100, -34, -102, -72, -32]); | ||
| static #keyType = { name: 'AES-GCM', length: 256 }; | ||
| static #algorithm = { name: 'AES-GCM', iv: this.#iv }; | ||
| static #wrappingKeyBuffer = new Uint8Array([81, -21, 31, -34, 109, 47, -19, 122, -31, -45, 127, -83, 10, -15, 126, -68, 99, -6, -87, 54, -24, 107, -44, 111, 124, -36, -102, 109, -108, 120, 63, 57]); | ||
| static #wrappingKey: CryptoKey | null = null; | ||
|
|
||
| private constructor(key: CryptoKey | null) { | ||
| this.#key = key; | ||
| } | ||
|
|
||
| encrypt = async (str: string): Promise<string> => { | ||
| if (crypto && this.#key) { | ||
| const cr = await crypto.subtle.encrypt(Crypto.#algorithm, this.#key, this.enc.encode(str)); | ||
| return JSON.stringify(Array.from(new Int8Array(cr))); | ||
| } | ||
| else return str; | ||
| } | ||
|
|
||
| decrypt = async (str: string): Promise<string> => { | ||
| if (crypto && this.#key) { | ||
| try { | ||
| const parsedBuffer = new Int8Array(JSON.parse(str)); | ||
| const dc = await crypto.subtle.decrypt(Crypto.#algorithm, this.#key, parsedBuffer.buffer); | ||
| return this.dec.decode(dc); | ||
| } | ||
| catch (e) { | ||
| return 'null'; | ||
| } | ||
| } | ||
| else return str; | ||
| } | ||
|
|
||
| static async generateKey(wrappingKey: CryptoKey) { | ||
| const cryptoKey = await crypto.subtle.generateKey(this.#keyType, true, ['encrypt', 'decrypt']); | ||
| const wrappedKey = await crypto.subtle.wrapKey('raw', cryptoKey, wrappingKey, this.#algorithm); | ||
| localStorage.setItem('secure_reactive_storage', JSON.stringify(Array.from(new Int8Array(wrappedKey)))); | ||
| return cryptoKey; | ||
| } | ||
|
|
||
| static async createInstance() { | ||
| if (crypto) { | ||
| let cryptoKey: CryptoKey | null = null; | ||
| this.#wrappingKey = await crypto.subtle.importKey('raw', this.#wrappingKeyBuffer, this.#algorithm.name, false, ['wrapKey', 'unwrapKey']) | ||
|
|
||
| const currentKey = localStorage.getItem('secure_reactive_storage'); | ||
| if (currentKey) { | ||
| try { | ||
| const keyBuffer = new Int8Array(JSON.parse(currentKey)) | ||
| cryptoKey = await crypto.subtle.unwrapKey('raw', keyBuffer, this.#wrappingKey, this.#algorithm, this.#algorithm.name, true, ['encrypt', 'decrypt']); | ||
| } catch { | ||
| cryptoKey = await this.generateKey(this.#wrappingKey); | ||
| } | ||
| } | ||
| else { | ||
| cryptoKey = await this.generateKey(this.#wrappingKey); | ||
| } | ||
|
|
||
| return new Crypto(cryptoKey as CryptoKey); | ||
| } | ||
| else return new Crypto(null); | ||
| } | ||
| } | ||
|
|
||
| const encryption = await Crypto.createInstance(); | ||
| export { encryption }; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,2 @@ | ||
| export { useLsState } from "./hooks/useLsState"; | ||
| export { ReactiveStorage } from "./ReactiveStorage"; |