diff --git a/README.md b/README.md index 39f939b..9e49da6 100644 --- a/README.md +++ b/README.md @@ -1,191 +1,175 @@ -[![npm](https://img.shields.io/npm/v/react-secure-storage.svg)](https://www.npmjs.com/package/react-secure-storage) [![downloads](https://img.shields.io/npm/dm/react-secure-storage.svg)](http://npm-stat.com/charts.html?package=react-secure-storage) - -## The problem statement! - -Most of the people save data into local storage, Is this a safe method to store ? No! Local storage writes the data as a plan string and any one who has the access to the device can read this data and manipulate. - -Most of the people thinks that we can encrypt the data and save it on local storage, But in this case, you need to have a secure key to decrypt this data, - -Let's consider this **Scenario**, You have encrypted the user login information and saved on local storage, When the platform reload, You are decrypting the data which is written on local storage and marking the user as logged or logged out, Here your website share a common secure key to encrypt and decrypt, which means only your website knows how to decrypt, - -In this case, if someone copies the data from local storage and past on a different browser, then load your website, Your website will authenticate the user, Why ? because your website knows how to decrypt the data! - -This is the problem when you have a single secure key! **Then how do we solve this issue ?** - - - -## Why React Secure Storage ? - -React secure storage is created to securely write the data to local storage ( **Basically its a wrapper written on top of default localStorage to write the data securely to the localStorage** ), here secure storage library generate a secure key for every browser and encrypt the data using this key, which means only the browser which encrypted the data can decrypt it, - -Additionally react secure storage preserve the data format for every data type, As out of the box it supports the following data types +# react-secure-storage -**String | Object | Number | Boolean** - -Which means you don't need to explicitly convert every data to string +[![npm](https://img.shields.io/npm/v/react-secure-storage.svg)](https://www.npmjs.com/package/react-secure-storage) [![downloads](https://img.shields.io/npm/dm/react-secure-storage.svg)](http://npm-stat.com/charts.html?package=react-secure-storage) +## Problem statement +Storing data in local storage is convenient, but is it safe? Unfortunately, no! Local storage saves data as plain strings, making it accessible to anyone with access to the device. -## How does it work ? +Many believe that encrypting data before storing it in local storage solves this issue. However, this introduces a new problem: if the decryption key is compromised, anyone can decrypt the data. For example, if you encrypt user login information and store it, a malicious user could copy this data and use it in a different browser to gain unauthorized access. -React secure storage is written in Singleton design pattern, and when the library initialized it reads all the data from local storage and decrypt all the data which is written using react-secure-storage and keeps on the memory, This ensure faster reading of all the data, +### How do we solve this issue? -The key is generated using browser fingerprint, which is generated using 10+ browser key identifiers and user input secure key, +## Why React Secure Storage? -The user specific Secure key can be configured using .env file as +`react-secure-storage` is designed to securely store data in local storage by generating a unique encryption key for each browser. This means that only the browser that encrypted the data can decrypt it. - SECURE_LOCAL_STORAGE_HASH_KEY=xxxxxxxxx +### Key Features +- **Data Types Supported**: Automatically preserves the data format for various types, including **String**, **Object**, **Number**, and **Boolean**. +- **Efficient Data Handling**: Utilizes a Singleton design pattern to read and decrypt data from local storage on initialization, ensuring fast access. +- **Unique Key Generation**: Generates a secure key using browser fingerprints (based on multiple identifiers) and an optional user-specific secure key. -Secure local storage prefix can be configured using .env file as +## Configuration - SECURE_LOCAL_STORAGE_PREFIX=xxxxxxx +You can specify a user-specific secure key in your `.env` file: +```plaintext +SECURE_LOCAL_STORAGE_HASH_KEY=xxxxxxxxx +``` +You can also configure a local storage prefix: -### Here are the .env prefix lists for the supported languages that are built-in. +```plaintext +SECURE_LOCAL_STORAGE_PREFIX=xxxxxxx +``` -| Language | Prefix | -|----------|--------------| -| React | REACT_APP_ | -| Vite | VITE_ | -| Next.Js | NEXT_PUBLIC_ | +### Built-in Prefixes for Supported Languages -You can always use the environment variables without the prefix as well +| Language | Prefix | +| -------- | ------------- | +| React | REACT_APP\_ | +| Vite | VITE\_ | +| Next.Js | NEXT_PUBLIC\_ | +You can use environment variables without the prefix as well. -## How to use +## How to Use -To use the library first you need to install using +Install the library using: - yarn add react-secure-storage +```bash +yarn add react-secure-storage +``` or - npm install react-secure-storage - -You can use the following methods to read and write items to secure local storage - -| Function |Usecase | Datatype | -|----------------|-------------------------------|-----------------------------| -|`setItem(key, value)` |To set values to secure storage |Supports `'String - Object - Number - Boolean'` as value | -|`getItem(key)` |To get values which is saved on secure local storage | Return null if the key does not exits | -|`removeItem(key)` | To remove specified key from secure local storage| | -|`clear()` | Removed all data from secure local storage| | - -## How to use with Vite - -In the latest version of Vite, process is not defined by default, It uses `import.meta.env`, +```bash +npm install react-secure-storage +``` -To define the process, You need to add the following code inside `vite.config.ts` +### API Methods - import { defineConfig } from 'vite' - // ... - export default defineConfig({ - // ... - define: { - "process.env": {}, - }, - }) +| Function | Use Case | Data Types Supported | +| --------------------- | ----------------------------------------- | ----------------------------------------------- | +| `setItem(key, value)` | Set values in secure storage | `'String'`, `'Object'`, `'Number'`, `'Boolean'` | +| `getItem(key)` | Retrieve values from secure local storage | Returns `null` if the key does not exist | +| `removeItem(key)` | Remove a specific key from secure storage | | +| `clear()` | Remove all data from secure local storage | | -Here you can pass all the required `ENV` variables supported by the library inside the process.env object +## Using with Vite -## To disable properties from key generation +In the latest version of Vite, `process` is not defined by default. You need to add the following to `vite.config.ts`: -If you wish to disable any of the key generation property, You can do it as below +```javascript +import { defineConfig } from "vite" +// ... +export default defineConfig({ + // ... + define: { + "process.env": {}, + }, +}) +``` - SECURE_LOCAL_STORAGE_DISABLED_KEYS=ScreenPrint|Plugins -or - - REACT_APP_SECURE_LOCAL_STORAGE_DISABLED_KEYS=ScreenPrint|Plugins +### Disabling Key Generation Properties -Here is the list of all the supported values `UserAgent|ScreenPrint|Plugins|Fonts|LocalStorage|SessionStorage|TimeZone|Language|SystemLanguage|Cookie|Canvas|Hostname` +To disable specific key generation properties, set the following in your `.env`: ->Here we strongly recommend you to not to disable any of the properties as more properties you have, more unique the browser fingerprint will be! +```plaintext +SECURE_LOCAL_STORAGE_DISABLED_KEYS=ScreenPrint|Plugins +``` +Supported values: +`UserAgent|ScreenPrint|Plugins|Fonts|LocalStorage|SessionStorage|TimeZone|Language|SystemLanguage|Cookie|Canvas|Hostname` +> Note: It's recommended to keep as many properties enabled as possible to ensure a unique browser fingerprint. -### How to use environment variables for the supported languages. +### Environment Variables for Supported Languages -| Language | Key | Usage | -|----------|------------------------------------------------|----------------------------------------------------------------------------------| -| Default | SECURE_LOCAL_STORAGE_HASH_KEY | Used to specify the user specific hash key | -| Default | SECURE_LOCAL_STORAGE_PREFIX | Used to change the local storage prefix where the data will be finally saved | -| Default | SECURE_LOCAL_STORAGE_DISABLED_KEYS | Used to disable individual property from encryption / fingerprint key generation | -| React | REACT_APP_SECURE_LOCAL_STORAGE_HASH_KEY | Used to specify the user specific hash key | -| React | REACT_APP_SECURE_LOCAL_STORAGE_PREFIX | Used to change the local storage prefix where the data will be finally saved | -| React | REACT_APP_SECURE_LOCAL_STORAGE_DISABLED_KEYS | Used to disable individual property from encryption / fingerprint key generation | -| Vite | VITE_SECURE_LOCAL_STORAGE_HASH_KEY | Used to specify the user specific hash key | -| Vite | VITE_SECURE_LOCAL_STORAGE_PREFIX | Used to change the local storage prefix where the data will be finally saved | -| Vite | VITE_SECURE_LOCAL_STORAGE_DISABLED_KEYS | Used to disable individual property from encryption / fingerprint key generation | -| Next.Js | NEXT_PUBLIC_SECURE_LOCAL_STORAGE_HASH_KEY | Used to specify the user specific hash key | -| Next.Js | NEXT_PUBLIC_SECURE_LOCAL_STORAGE_PREFIX | Used to change the local storage prefix where the data will be finally saved | -| Next.Js | NEXT_PUBLIC_SECURE_LOCAL_STORAGE_DISABLED_KEYS | Used to disable individual property from encryption / fingerprint key generation | +| Language | Key | Usage | +| -------- | ---------------------------------------------- | ------------------------------------------------- | +| Default | SECURE_LOCAL_STORAGE_HASH_KEY | User-specific hash key | +| Default | SECURE_LOCAL_STORAGE_PREFIX | Change local storage prefix for saved data | +| Default | SECURE_LOCAL_STORAGE_DISABLED_KEYS | Disable individual properties from key generation | +| React | REACT_APP_SECURE_LOCAL_STORAGE_HASH_KEY | User-specific hash key | +| React | REACT_APP_SECURE_LOCAL_STORAGE_PREFIX | Change local storage prefix for saved data | +| React | REACT_APP_SECURE_LOCAL_STORAGE_DISABLED_KEYS | Disable individual properties from key generation | +| Vite | VITE_SECURE_LOCAL_STORAGE_HASH_KEY | User-specific hash key | +| Vite | VITE_SECURE_LOCAL_STORAGE_PREFIX | Change local storage prefix for saved data | +| Vite | VITE_SECURE_LOCAL_STORAGE_DISABLED_KEYS | Disable individual properties from key generation | +| Next.js | NEXT_PUBLIC_SECURE_LOCAL_STORAGE_HASH_KEY | User-specific hash key | +| Next.js | NEXT_PUBLIC_SECURE_LOCAL_STORAGE_PREFIX | Change local storage prefix for saved data | +| Next.js | NEXT_PUBLIC_SECURE_LOCAL_STORAGE_DISABLED_KEYS | Disable individual properties from key generation | ## Sample Code - - import { useEffect } from "react"; - import secureLocalStorage from "react-secure-storage"; - - - const App = () => { - useEffect(() => { - secureLocalStorage.setItem("object", { - message: "This is testing of local storage", - }); - secureLocalStorage.setItem("number", 12); - secureLocalStorage.setItem("string", "12"); - secureLocalStorage.setItem("boolean", true); - let value = secureLocalStorage.getItem("boolean"); - }, []); - - return ( -
- This is a sample code -
- ); - } - - export default App; - - -## Build Size ! 7.6KB - -## Whats new in 1.3.2? +```javascript +import { useEffect } from "react" +import secureLocalStorage from "react-secure-storage" -Regular bug fixes and https://github.com/sushinpv/react-secure-storage/issues/39 is resolved +const App = () => { + useEffect(() => { + secureLocalStorage.setItem("object", { + message: "This is a test for local storage", + }) + secureLocalStorage.setItem("number", 12) + secureLocalStorage.setItem("string", "12") + secureLocalStorage.setItem("boolean", true) + let value = secureLocalStorage.getItem("boolean") + }, []) -## Whats new | Previous? + return
This is a sample code
+} -Added support for Vite and Next.js environment variables +export default App +``` -Now you can disable individual fingerprint generation properties, This is discussed in the following enhancement https://github.com/sushinpv/react-secure-storage/issues/14 +## Build Size -Secure token returning null when the browser resizes problem was fixed. This was previously included as a security feature, but in the most recent update, it was removed. This was covered in the ensuing issue: https://github.com/sushinpv/react-secure-storage/issues/9 +7.6KB -Now that we have included the browser hostname while establishing the secure key, it is more unique. This will guarantee that each website's key is distinct. +## Whats new in 1.3.2? -Added support for updating Local Storage prefix, Now this can be updated using .env +- Regular bug fixes and [#39](https://github.com/sushinpv/react-secure-storage/issues/39) is resolved -Resolved https://github.com/sushinpv/react-secure-storage/issues/2 +## Previous Updates? -Added support for `Cypress` +- Added support for Vite and Next.js environment variables. +- Introduced functionality to disable individual fingerprint generation properties as discussed in [#14](https://github.com/sushinpv/react-secure-storage/issues/14). +- Resolved issues related to secure token handling and unique key generation based on browser hostname. +- Added support for `Cypress` and enhance type definitions. +- Removed `react-scripts` dependency due to vulnerability concerns, as noted in [#3](https://github.com/sushinpv/react-secure-storage/issues/3). -Added proper type definition for the entire package +## Testing and Contribution -Added support for older es versions and nextjs +To test the library locally, ensure you have `react-scripts` installed: -Releasing the first version of react secure local storage, which supports `setItem`, `getItem`, `removeItem` and `clear` functions +```bash +npm i react-scripts +``` -## How do I test this library on my local system & How do I contribute ? +or -For local testing the library make sure you are installing the `react-scripts` by using `npm i react-scripts` or `yarn add react-scripts`. -The react-scripts is removed due to vulnerability issue which is highlighted in here : https://github.com/sushinpv/react-secure-storage/issues/3 +```bash +yarn add react-scripts +``` -To contribute on the library, make sure you are creating a development branch for your fix as `dev/{feature/fix}` and create a PR to master branch. +To contribute, create a development branch for your fix as `dev/{feature/fix}` and submit a PR to the master branch. Before creating the PR, ensure you remove `react-scripts` from `package.json` and create a production build for the library: -Before creating the PR, Please make sure to remove the `react-scripts` from the `package.json`. and you are creating a production build for the library by running `yarn build:lib` +```bash +yarn build:lib +``` ## Star History