Loading...
Please waitLoading...
Please waitTransparent encryption layer for local/session storage with key rotation and optional server-backed key retrieval for tokens and sensitive settings.
pnpm dlx uselab@latest add use-secure-storage
import * as React from "react"
import { useSecureStorage } from "@/hooks/use-secure-storage"
export function Component() {
const {
value: token,
setValue: setToken,
remove: removeToken,
} = useSecureStorage("auth-token", "", {
storageType: "localStorage",
ttl: 3600000, // 1 hour
})
return (
<div>
<button onClick={() => setToken("secret-token-123")}>Store Token</button>
<button onClick={removeToken}>Clear Token</button>
</div>
)
}| Name | Type | Description | Default Value | Optional |
|---|---|---|---|---|
name | string | Storage key name. | — | No |
initialValue | T | (() => T) | Initial value or function that returns initial value. | — | No |
options | UseSecureStorageOptions | Configuration object for secure storage. | {} | Yes |
storageType | "localStorage" | "sessionStorage" | Type of storage to use. | "localStorage" | Yes |
ttl | number | Time-to-live in milliseconds. Value expires after this duration. | undefined | Yes |
rotateKeyFn | () => Promise<string> | string | Function to retrieve a new encryption key for rotation. | undefined | Yes |
serverKeyEndpoint | string | Server endpoint URL to fetch encryption key from. | undefined | Yes |
encryptionKey | string | Static encryption key (if provided, overrides other key sources). | undefined | Yes |
| Name | Type | Description |
|---|---|---|
value | T | Current decrypted value from storage. |
setValue | (value: SetStateAction<T>) => void | Function to store an encrypted value. Returns a promise. |
remove | () => void | Function to remove the stored value and clear encryption keys. |
The hook supports multiple key sources with the following priority:
encryptionKey) - Highest priority, always used if providedserverKeyEndpoint) - Fetched from server endpointrotateKeyFn) - Generated via rotation functionKeys are versioned to support rotation. When rotating keys, the hook increments the version and stores the new key separately.
const {
value: token,
setValue: setToken,
remove: removeToken,
} = useSecureStorage("auth-token", "")
// Store encrypted value
await setToken("my-secret-token")
// Value is automatically decrypted when read
console.log(token) // "my-secret-token"const { value: session, setValue: setSession } = useSecureStorage(
"user-session",
null,
{
ttl: 3600000, // Expires after 1 hour
}
)
// Value automatically expires and is removed after TTLconst { value: sensitiveData, setValue: setSensitiveData } = useSecureStorage(
"data",
"",
{
serverKeyEndpoint: "/api/encryption-key",
}
)
// Key is fetched from server on first useconst { value, setValue } = useSecureStorage("data", "", {
rotateKeyFn: async () => {
// Fetch new key from server or generate
const response = await fetch("/api/new-key")
const { key } = await response.json()
return key
},
})const { value: tempData, setValue: setTempData } = useSecureStorage(
"temp",
"",
{
storageType: "sessionStorage",
ttl: 1800000, // 30 minutes
}
)initialValueNo data stored yet