safe-session-storage 1.0.0

package/README.md

@@ -0,0 +1,94 @@
+# safe-session-storage
+
+A secure, lightweight wrapper for `localStorage`, `sessionStorage`, and `AsyncStorage` (React Native) with automatic encryption. Prevent casual inspection of your application's stored data across all platforms.
+
+## Features
+
+- 🔐 **Automatic Encryption**: Data is encrypted before being stored.
+- ⚛️ **React & React Native Support**: Hooks for both synchronous and asynchronous storage.
+- 🌐 **SSR Friendly**: Works perfectly with Next.js and other SSR frameworks.
+- 📦 **Zero External Dependencies**: Lightweight and fast.
+- 🛡️ **Type Safe**: Full TypeScript support.
+
+## Installation
+
+```bash
+npm install safe-session-storage
+```
+
+## Platform Support
+
+### 1. Web (React, Vite, etc.)
+Use `useSafeStorage` for synchronous `localStorage` or `sessionStorage`.
+
+```tsx
+import { useSafeStorage } from 'safe-session-storage';
+
+function App() {
+  const [theme, setTheme] = useSafeStorage('theme', 'light');
+  // ...
+}
+```
+
+### 2. Next.js (SSR)
+`useSafeStorage` is SSR-safe. It detects the environment and returns the initial value during server-side rendering, then hydrates correctly on the client.
+
+### 3. React Native
+Use `useAsyncSafeStorage` with `@react-native-async-storage/async-storage`.
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { useAsyncSafeStorage } from 'safe-session-storage';
+
+function Profile() {
+  const [user, setUser, loading] = useAsyncSafeStorage('user', null, {
+    customStorage: AsyncStorage,
+    secretKey: 'my-mobile-secret'
+  });
+
+  if (loading) return <Text>Loading...</Text>;
+  // ...
+}
+```
+
+## Usage
+
+### Vanilla JavaScript / TypeScript
+
+```typescript
+import { safeLocal, SafeStorage, AsyncSafeStorage } from 'safe-session-storage';
+
+// Web (Sync)
+safeLocal.setItem('key', 'value');
+
+// React Native / Custom (Async)
+const asyncStore = new AsyncSafeStorage({ 
+  customStorage: AsyncStorage,
+  secretKey: 'key' 
+});
+await asyncStore.setItem('key', 'value');
+```
+
+## Why use this?
+
+When you store data in storage engines, it is usually stored in plain text. Anyone with access to the device or a malicious script can easily read this data.
+
+`safe-session-storage` obfuscates this data using XOR encryption and Base64 encoding. It works across:
+- **Browsers**: Chrome, Firefox, Safari, Edge.
+- **Server**: Node.js (SSR safe).
+- **Mobile**: React Native (iOS/Android).
+
+## API
+
+### Web (Sync)
+- `useSafeStorage(key, initialValue, options)`
+- `safeLocal` / `safeSession` instances.
+- `SafeStorage` class.
+
+### Mobile/Custom (Async)
+- `useAsyncSafeStorage(key, initialValue, options)`
+- `AsyncSafeStorage` class.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var I=Object.create;var y=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var V=Object.getOwnPropertyNames;var K=Object.getPrototypeOf,O=Object.prototype.hasOwnProperty;var x=(r,t)=>{for(var e in t)y(r,e,{get:t[e],enumerable:!0})},h=(r,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of V(t))!O.call(r,o)&&o!==e&&y(r,o,{get:()=>t[o],enumerable:!(s=v(t,o))||s.enumerable});return r};var E=(r,t,e)=>(e=r!=null?I(K(r)):{},h(t||!r||!r.__esModule?y(e,"default",{value:r,enumerable:!0}):e,r)),J=r=>h(y({},"__esModule",{value:!0}),r);var b={};x(b,{AsyncSafeStorage:()=>f,SafeStorage:()=>u,safeLocal:()=>T,safeSession:()=>w,simpleDecrypt:()=>S,simpleEncrypt:()=>m,useAsyncSafeStorage:()=>P,useSafeStorage:()=>N});module.exports=J(b);var i=require("react"),p=E(require("crypto-js"),1),m=(r,t)=>{try{return p.default.AES.encrypt(r,t).toString()}catch(e){return console.error("Encryption failed:",e),r}},S=(r,t)=>{try{return p.default.AES.decrypt(r,t).toString(p.default.enc.Utf8)}catch(e){return console.error("Decryption failed:",e),""}},u=class{storage=null;secretKey;constructor(t={}){let{secretKey:e="safe-storage-default-key",storageType:s="local"}=t;this.secretKey=e,typeof window<"u"&&(this.storage=s==="local"?window.localStorage:window.sessionStorage)}setItem(t,e){if(!this.storage)return;let s=JSON.stringify(e),o=m(s,this.secretKey);this.storage.setItem(t,o)}getItem(t){if(!this.storage)return null;let e=this.storage.getItem(t);if(!e)return null;let s=S(e,this.secretKey);try{return JSON.parse(s)}catch{return null}}removeItem(t){this.storage&&this.storage.removeItem(t)}clear(){this.storage&&this.storage.clear()}},f=class{storage;secretKey;constructor(t={}){let{secretKey:e="safe-storage-default-key",customStorage:s}=t;this.secretKey=e,this.storage=s}async setItem(t,e){if(!this.storage)return;let s=JSON.stringify(e),o=m(s,this.secretKey);await this.storage.setItem(t,o)}async getItem(t){if(!this.storage)return null;let e=await this.storage.getItem(t);if(!e)return null;let s=S(e,this.secretKey);try{return JSON.parse(s)}catch{return null}}async removeItem(t){this.storage&&await this.storage.removeItem(t)}async clear(){this.storage&&await this.storage.clear()}},T=new u({storageType:"local"}),w=new u({storageType:"session"});function N(r,t,e={}){let[s,o]=(0,i.useState)(!1),c=e.storageType==="session"?w:T,[g,l]=(0,i.useState)(()=>{if(typeof window>"u")return t;try{let a=c.getItem(r);return a!==null?a:t}catch{return t}});(0,i.useEffect)(()=>{o(!0)},[]);let d=(0,i.useCallback)(a=>{try{let n=a instanceof Function?a(g):a;l(n),c.setItem(r,n)}catch(n){console.error(n)}},[r,c,g]);return[s?g:t,d]}function P(r,t,e){let[s,o]=(0,i.useState)(t),[c,g]=(0,i.useState)(!0),l=new f(e);(0,i.useEffect)(()=>{(async()=>{try{let n=await l.getItem(r);n!==null&&o(n)}catch(n){console.error(n)}finally{g(!1)}})()},[r]);let d=(0,i.useCallback)(async a=>{try{let n=a instanceof Function?a(s):a;o(n),await l.setItem(r,n)}catch(n){console.error(n)}},[r,l,s]);return[s,d,c]}0&&(module.exports={AsyncSafeStorage,SafeStorage,safeLocal,safeSession,simpleDecrypt,simpleEncrypt,useAsyncSafeStorage,useSafeStorage});

package/dist/index.d.cts

@@ -0,0 +1,47 @@
+type StorageType = 'local' | 'session' | 'async';
+interface SafeStorageOptions {
+    secretKey?: string;
+    storageType?: StorageType;
+    customStorage?: any;
+}
+/**
+ * Military-grade AES encryption for storage values.
+ */
+declare const simpleEncrypt: (text: string, key: string) => string;
+declare const simpleDecrypt: (encoded: string, key: string) => string;
+/**
+ * Synchronous Storage Wrapper (Web)
+ */
+declare class SafeStorage {
+    private storage;
+    private secretKey;
+    constructor(options?: SafeStorageOptions);
+    setItem(key: string, value: any): void;
+    getItem<T = any>(key: string): T | null;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Asynchronous Storage Wrapper (React Native / Custom)
+ */
+declare class AsyncSafeStorage {
+    private storage;
+    private secretKey;
+    constructor(options?: SafeStorageOptions);
+    setItem(key: string, value: any): Promise<void>;
+    getItem<T = any>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare const safeLocal: SafeStorage;
+declare const safeSession: SafeStorage;
+/**
+ * React Hook for Synchronous Storage (Web/Next.js)
+ */
+declare function useSafeStorage<T>(key: string, initialValue: T, options?: SafeStorageOptions): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * React Hook for Asynchronous Storage (React Native)
+ */
+declare function useAsyncSafeStorage<T>(key: string, initialValue: T, options: SafeStorageOptions): readonly [T, (value: T | ((val: T) => T)) => Promise<void>, boolean];
+
+export { AsyncSafeStorage, SafeStorage, safeLocal, safeSession, simpleDecrypt, simpleEncrypt, useAsyncSafeStorage, useSafeStorage };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+type StorageType = 'local' | 'session' | 'async';
+interface SafeStorageOptions {
+    secretKey?: string;
+    storageType?: StorageType;
+    customStorage?: any;
+}
+/**
+ * Military-grade AES encryption for storage values.
+ */
+declare const simpleEncrypt: (text: string, key: string) => string;
+declare const simpleDecrypt: (encoded: string, key: string) => string;
+/**
+ * Synchronous Storage Wrapper (Web)
+ */
+declare class SafeStorage {
+    private storage;
+    private secretKey;
+    constructor(options?: SafeStorageOptions);
+    setItem(key: string, value: any): void;
+    getItem<T = any>(key: string): T | null;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Asynchronous Storage Wrapper (React Native / Custom)
+ */
+declare class AsyncSafeStorage {
+    private storage;
+    private secretKey;
+    constructor(options?: SafeStorageOptions);
+    setItem(key: string, value: any): Promise<void>;
+    getItem<T = any>(key: string): Promise<T | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare const safeLocal: SafeStorage;
+declare const safeSession: SafeStorage;
+/**
+ * React Hook for Synchronous Storage (Web/Next.js)
+ */
+declare function useSafeStorage<T>(key: string, initialValue: T, options?: SafeStorageOptions): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * React Hook for Asynchronous Storage (React Native)
+ */
+declare function useAsyncSafeStorage<T>(key: string, initialValue: T, options: SafeStorageOptions): readonly [T, (value: T | ((val: T) => T)) => Promise<void>, boolean];
+
+export { AsyncSafeStorage, SafeStorage, safeLocal, safeSession, simpleDecrypt, simpleEncrypt, useAsyncSafeStorage, useSafeStorage };

package/dist/index.js

@@ -0,0 +1 @@
+import{useState as l,useEffect as d,useCallback as m}from"react";import p from"crypto-js";var S=(s,t)=>{try{return p.AES.encrypt(s,t).toString()}catch(e){return console.error("Encryption failed:",e),s}},h=(s,t)=>{try{return p.AES.decrypt(s,t).toString(p.enc.Utf8)}catch(e){return console.error("Decryption failed:",e),""}},u=class{storage=null;secretKey;constructor(t={}){let{secretKey:e="safe-storage-default-key",storageType:r="local"}=t;this.secretKey=e,typeof window<"u"&&(this.storage=r==="local"?window.localStorage:window.sessionStorage)}setItem(t,e){if(!this.storage)return;let r=JSON.stringify(e),a=S(r,this.secretKey);this.storage.setItem(t,a)}getItem(t){if(!this.storage)return null;let e=this.storage.getItem(t);if(!e)return null;let r=h(e,this.secretKey);try{return JSON.parse(r)}catch{return null}}removeItem(t){this.storage&&this.storage.removeItem(t)}clear(){this.storage&&this.storage.clear()}},f=class{storage;secretKey;constructor(t={}){let{secretKey:e="safe-storage-default-key",customStorage:r}=t;this.secretKey=e,this.storage=r}async setItem(t,e){if(!this.storage)return;let r=JSON.stringify(e),a=S(r,this.secretKey);await this.storage.setItem(t,a)}async getItem(t){if(!this.storage)return null;let e=await this.storage.getItem(t);if(!e)return null;let r=h(e,this.secretKey);try{return JSON.parse(r)}catch{return null}}async removeItem(t){this.storage&&await this.storage.removeItem(t)}async clear(){this.storage&&await this.storage.clear()}},T=new u({storageType:"local"}),w=new u({storageType:"session"});function V(s,t,e={}){let[r,a]=l(!1),i=e.storageType==="session"?w:T,[c,g]=l(()=>{if(typeof window>"u")return t;try{let n=i.getItem(s);return n!==null?n:t}catch{return t}});d(()=>{a(!0)},[]);let y=m(n=>{try{let o=n instanceof Function?n(c):n;g(o),i.setItem(s,o)}catch(o){console.error(o)}},[s,i,c]);return[r?c:t,y]}function K(s,t,e){let[r,a]=l(t),[i,c]=l(!0),g=new f(e);d(()=>{(async()=>{try{let o=await g.getItem(s);o!==null&&a(o)}catch(o){console.error(o)}finally{c(!1)}})()},[s]);let y=m(async n=>{try{let o=n instanceof Function?n(r):n;a(o),await g.setItem(s,o)}catch(o){console.error(o)}},[s,g,r]);return[r,y,i]}export{f as AsyncSafeStorage,u as SafeStorage,T as safeLocal,w as safeSession,h as simpleDecrypt,S as simpleEncrypt,K as useAsyncSafeStorage,V as useSafeStorage};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "safe-session-storage",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A secure wrapper for localStorage and sessionStorage with automatic encryption.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --minify --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "test": "vitest run",
+    "lint": "tsc"
+  },
+  "keywords": [
+    "storage",
+    "security",
+    "encryption",
+    "localstorage",
+    "sessionstorage",
+    "react",
+    "hook"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/crypto-js": "^4.2.2",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "jsdom": "^29.0.2",
+    "react": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.5"
+  },
+  "dependencies": {
+    "crypto-js": "^4.2.0"
+  }
+}