DEV Community

V G P
V G P

Posted on

I Built a Zero-Dependency Browser Storage Encryption Library — Here's Why

#webdev #javascript #typescript #security

A few months ago I found myself auditing a side project and noticed something uncomfortable: I was storing sensitive user preferences, cart data, and session tokens in localStorage — completely in plaintext. Anyone with DevTools open could read it in two seconds.

The obvious fix is "just encrypt it." But when I went looking for a library that actually did this well, I kept running into the same problems: heavy dependencies, weak key derivation, or APIs that felt bolted on as an afterthought. So I built tessera.

What tessera does

One passcode. All your browser storage — localStorage, sessionStorage, IndexedDB, and cookies — encrypted with AES-256-GCM. The key is derived from PBKDF2-SHA-256 at ≥ 310,000 iterations (the OWASP 2024 minimum), and it never leaves the Web Crypto engine as raw bytes.

The API is a drop-in replacement for the storage APIs you already use:

import { Tessera } from '@mrtinkz/tessera';

const vault = await Tessera.unlock('abc123');
await vault.local.setItem('cart', JSON.stringify(cartData));
const cart = await vault.local.getItem('cart'); // plaintext back
vault.lock(); // zeroes the in-memory key
Enter fullscreen mode Exit fullscreen mode

No server round-trips. No cloud keys. No dependencies.

The threat model I was actually designing against

Most encryption libraries stop at "we encrypt the data." tessera is built against the OWASP browser storage threat model, so let me be specific about what it protects and what it doesn't.

What it protects against:

  • Passive observer in DevTools — storage values are ciphertext. Useless without the key.
  • XSS reading storage — same deal. The attacker gets ciphertext.
  • Offline brute force — PBKDF2 at 310k iterations costs roughly 1 second per attempt on modern hardware.
  • Key exfiltration via heap dump — extractable: false means the raw key bytes never exist in JavaScript memory.
  • On-device brute force — configurable lockout: wipe all storage, apply exponential backoff, or throw immediately after N failed attempts.

What it doesn't protect against:

tessera protects your data at rest — when the vault is locked, everything in storage is ciphertext. Unlocking doesn't decrypt everything at once; it just derives the key and holds it in memory. Individual values only decrypt on demand when you call getItem.

The one scenario where this breaks down is if your page already has an XSS vulnerability. An attacker running code on your page has the same access you do — they can call vault.local.getItem() while the vault is unlocked and get plaintext back, one value at a time. They can't steal the raw key bytes (extractable: false blocks that), but they don't need to. Fix XSS first; tessera handles the rest. The threat model docs go deeper on this.

The crypto internals

Each stored value gets its own salt and IV. The stored format is:

salt(16) ‖ iv(12) ‖ ciphertext ‖ tag(16)
Enter fullscreen mode Exit fullscreen mode

The vault salt lives in localStorage so the same passcode re-derives the same key across sessions — you unlock once per session, not once per page load.

Key derivation:

PBKDF2(passcode, vaultSalt, 310_000 iterations, SHA-256) → AES-256-GCM key
Enter fullscreen mode Exit fullscreen mode

The CryptoKey is created with extractable: false. The Web Crypto engine holds the key material; your JavaScript never sees the raw bytes.

The PIN pad problem

I wanted to mitigate keyloggers and click-sequence recording. The naive approach — an HTML grid of buttons with digit labels — fails because:

  1. Keyloggers read keydown events
  2. Click-sequence recording reads which DOM element was clicked
  3. The digit labels on buttons reveal the sequence

tessera ships a Canvas-based PIN pad. Digit positions are randomised on every render. No DOM element carries a digit value. A click recorder sees coordinates, not digits.

import { renderPinPad } from '@mrtinkz/tessera';

renderPinPad(document.getElementById('pin'), {
  onUnlock: async (passcode) => {
    const vault = await Tessera.unlock(passcode);
  },
  randomize: true,
  length: 6,
});
Enter fullscreen mode Exit fullscreen mode

You can style it with CSS custom properties:

.tessera-pin-pad {
  --tessera-pad-bg: #1a1a2e;
  --tessera-btn-bg: #16213e;
  --tessera-btn-color: #e2e8f0;
  --tessera-btn-hover: #0f3460;
  --tessera-btn-size: 64px;
  --tessera-indicator-color: #4ade80;
}
Enter fullscreen mode Exit fullscreen mode

Framework support

tessera ships ESM, CJS, and IIFE builds. There are native adapters for React, Vue 3, Svelte, and Angular so you get a hook/store/service rather than managing vault state yourself.

React:

'use client';
import { useTessera } from '@mrtinkz/tessera/react';

function SecureApp() {
  const { vault, isLocked, unlock, lock } = useTessera({ idleTimeout: 600_000 });

  if (isLocked) return <PinPad onUnlock={unlock} />;
  return <Dashboard vault={vault} onLock={lock} />;
}
Enter fullscreen mode Exit fullscreen mode

Vue 3:

<script setup lang="ts">
import { useTessera } from '@mrtinkz/tessera/vue';
const { vault, isLocked, unlock, lock } = useTessera({ idleTimeout: 600_000 });
</script>
Enter fullscreen mode Exit fullscreen mode

Svelte:

<script lang="ts">
  import { tesseraStore } from '@mrtinkz/tessera/svelte';
  const { vault, isLocked, unlock, lock } = tesseraStore({ idleTimeout: 600_000 });
</script>
Enter fullscreen mode Exit fullscreen mode

There's also an Angular TesseraModule and TesseraService if that's your stack.

Idle timeout and cross-tab sync

The vault auto-locks after a configurable idle period. When it locks, it broadcasts over BroadcastChannel so every open tab locks simultaneously. No stale unlocked tabs sitting in the background.

const vault = await Tessera.unlock('abc123', {
  idleTimeout: 900_000,    // 15 minutes
  lockoutAttempts: 5,
  lockoutAction: 'wipe',   // nuclear option
});
Enter fullscreen mode Exit fullscreen mode

Install 

npm install @mrtinkz/tessera
Enter fullscreen mode Exit fullscreen mode

CDN:

<script src="https://cdn.jsdelivr.net/npm/@mrtinkz/tessera/dist/index.global.global.js"></script>
<script>
  const { Tessera } = TesseraLib;
  Tessera.unlock('abc123').then((vault) => {
    vault.local.setItem('theme', 'dark');
  });
</script>
Enter fullscreen mode Exit fullscreen mode

Browser support: Chrome/Edge 89+, Firefox 86+, Safari 15+. Also works in Deno, Bun, and Cloudflare Workers.

I'd love feedback — especially from anyone who's thought hard about browser storage security. What's missing? What would you do differently? Drop it in the comments or open an issue on GitHub.

Top comments (0)