secure-storage

Keep login tokens and secrets in the phone or computer's secure vault instead of plain storage.

Device featuresClientServer

What it is

@kitr/secure-storage stores secrets such as tokens. Define an item with defineSecureItem, read it with useSecureItem. A secure flag says whether the value is in a real vault or the encrypted browser fallback, and a switch can refuse the fallback.

Runs in the browser and in native shells. For values that are not secret, use storage.

Install

kitr add secure-storage

First time? Run npm i -g @kitr/kitr once. Inside a project, the global kitr runs your project's own version.

Adds @kitr/secure-storage, its provider, config/secure-storage.ts and app/secure.ts with one item. Every change.

Quick start

An item names a key and the type of what is stored under it:

// app/secure.ts
import { defineSecureItem } from '@kitr/secure-storage'

export const sessionItem = defineSecureItem<{ token: string; expiresAt: number }>('session')

Read and write it in a component with useSecureItem:

// app/features/account/session-status.tsx
import { useSecureItem } from '@kitr/secure-storage/react'
import { sessionItem } from '#app/secure'

export function SessionStatus() {
  const [session, setSession, { loading, secure }] = useSecureItem(sessionItem)
  if (loading) return null
  if (!session)
    return (
      <button type="button" onClick={() => setSession({ token: 'tok_ada_7f3k', expiresAt: Date.now() + 3_600_000 })}>
        Sign in as Ada
      </button>
    )
  return (
    <p>
      Signed in{secure ? '' : ' (browser storage)'}.{' '}
      <button type="button" onClick={() => setSession(undefined)}>
        Sign out
      </button>
    </p>
  )
}

Click Sign in as Ada and reload: still signed in. localStorage holds ciphertext, not the token. With a vault driver, secure becomes true. Next in the guide: Store your first secret.

Built on

Where Built on
iOS and Android The Keychain and the Keystore, through the mobile platform's driver.
Electron safeStorage, through the desktop platform's driver.
Browser and anywhere without a vault AES-GCM through the Web Crypto API, under a key the browser keeps in IndexedDB and never lets out.

kitr adds typed items, schema checks, the hook, the secure flag, the fallback switch, a memory driver and the SecureStorageDriver interface.

Problems it solves

Further reading