secure-token-encryption

A simple, drop‑in replacement for Web Storage with built‑in encryption using the Web Crypto API.

🚀 Overview

This library provides an easy, secure way to store encrypted data in localStorage or sessionStorage.
It wraps the Web Crypto API and offers a clean, simple API to store, retrieve, and manage encrypted values.

📦 Installation

npm i secure-token-encryption

🔥 Usage Example

import { storeToken, getToken } from "secure-token-encryption";

await storeToken("auth", "my-secret-token");

const token = await getToken("auth");
console.log(token);

📘 API Reference

🔐 Encryption & Storage Utilities

storeToken(key: string, value: string): Promise

Encrypts a value and stores it.

getToken(key: string): Promise<string | null>

Retrieves and decrypts a stored token.

clearToken(key: string): void

Removes one encrypted key.

hasToken(key: string): boolean

Checks whether a stored encrypted key exists.

resetAll(): void

Clears all encrypted values stored by the library.

encrypt(data: string | object): Promise

Encrypts a value and returns the encrypted payload.

decrypt(payload: EncryptedData): Promise

Decrypts previously encrypted data.

arrayBufferToBase64(buffer: ArrayBuffer): string

Convert ArrayBuffer → Base64.

base64ToArrayBuffer(base64: string): ArrayBuffer

Convert Base64 → ArrayBuffer.

🧩 Buffered String Helpers

storeEncryptedString(key: string, value: string): Promise

Encrypts and stores a raw string.

getDecryptedString(key: string): Promise<string | null>

Retrieves and decrypts a buffered string.

🔑 Key Management

getOrCreateKey(): Promise

Creates or retrieves a persistent AES-GCM key.

clearCachedKey(): Promise

Deletes the cached key so a new one will be generated.

🧾 Types

EncryptedData

type EncryptedData = {
  iv: string;      // Base64 encoded IV
  cipher: string;  // Base64 encoded encrypted payload
};

StorageOptions

type StorageOptions = {
  storage?: Storage; // default: localStorage
  keyName?: string;
};

🛠 Development

git clone https://github.com/KerlosSoNy/secure-token-encryption.git
cd secure-token-encryption
npm install
npm run build

📄 License

MIT License