From 503d77d42cc7030a871aa51392ddfcd501d4f979 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 29 Aug 2026 08:11:59 +0000
Subject: [PATCH] =?UTF-8?q?feat(vault):=20phase=201=20=E2=80=94=20crypto?=
 =?UTF-8?q?=20core,=20schema=20and=20API?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First of four phases toward an end-to-end encrypted password manager. No
user-visible surface yet: this is the layer everything else sits on, so it
lands with its own tests and nothing depending on it.

Decision taken (section 01 of the plan): a SEPARATE vault password, not the
account password. MarkSyncr authenticates with signInWithPassword, so
Supabase receives the account password in plaintext and it therefore cannot
be an encryption key without giving up the end-to-end property. The
alternative — deriving an auth hash client-side so the real password is
never transmitted — is better UX and a stronger story, but it rewrites the
live login path and migrates every existing user, and that risk lands on
the bookmark sync that already works. It stays open: KDF parameters are
stored per user, so adopting it later invalidates nobody's vault.

packages/vault is shared by web and extension:

  primitives.js  Thin WebCrypto wrappers and nothing else — PBKDF2-SHA256,
                 HKDF-SHA256, AES-256-GCM, constant-time compare. Nothing in
                 the vault may implement a construction not in this file.
  kdf.js         master password -> masterKey -> {wrapKey, authHash} by HKDF
                 under distinct labels, so holding the auth hash does not
                 help decrypt anything. Labels are versioned and append-only:
                 editing one makes every existing vault unopenable.
  vault-key.js   A random user key encrypts items; the password only ever
                 encrypts that key. So a password change re-wraps 32 bytes
                 instead of re-encrypting the vault, and a second wrapped
                 copy under a recovery key survives a forgotten password
                 without the server learning anything.
  items.js       One record with three field groups — logins, cards,
                 identities are not three features. Password history is an
                 array inside the encrypted blob, so it is protected for
                 free rather than needing its own table.

PBKDF2 at 600k iterations rather than Argon2id: Argon2id is the better KDF
but is WASM in a browser, which means 'wasm-unsafe-eval' in the extension
CSP on a product already heading for review scrutiny. PBKDF2 is native, has
no dependency, and the per-user kdf/kdf_iterations columns mean the upgrade
later costs nothing. rewrapUserKey() already pulls a vault up to current
parameters on any password change.

Two attacks the code defends against explicitly, both tested:

  KDF downgrade. Parameters arrive from the server, so a compromised server
  could serve iterations: 1 and make captured auth hashes cheap to attack
  offline. The client refuses to derive below its floor; the API and a CHECK
  constraint refuse to store one.

  Ciphertext relocation. Each item's id is bound in as AES-GCM additional
  authenticated data, so a blob moved between rows fails to decrypt instead
  of showing the wrong credential under the right name.

The migration stores base64 TEXT, not BYTEA — bytea round-trips through
PostgREST as an escaped hex string and invites encoding mistakes on exactly
the values that must not be corrupted. vault_items is one row per item,
unlike cloud_bookmarks' single blob, because two devices editing two
DIFFERENT passwords must not cost anyone a credential; a per-row revision
turns that into a 409 the client can merge.

Tests: 97 new (67 in the package, 30 on the API validation). The KDF and
HKDF cases are known-answer tests against RFC 7914 §11 and RFC 5869 A.1/A.3
rather than round-trips — a round-trip passes even when the parameters are
wrong in both directions. One test asserts the actual product claim: that
nothing the user typed appears anywhere in what is sent.

Not done here: the migration is written but NOT applied to any database,
and nothing calls this code yet. Phase 2 is the vault tab.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q3vvUS9Q7m4ASyESCL2C8D
---
 apps/web/__tests__/vault-validation.test.js  | 155 ++++++++++++
 apps/web/app/api/vault/items/[id]/route.js   | 181 ++++++++++++++
 apps/web/app/api/vault/items/route.js        | 118 ++++++++++
 apps/web/app/api/vault/meta/route.js         | 145 ++++++++++++
 apps/web/lib/vault-validation.js             |  85 +++++++
 packages/vault/__tests__/items.test.js       | 220 +++++++++++++++++
 packages/vault/__tests__/primitives.test.js  | 181 ++++++++++++++
 packages/vault/__tests__/vault-key.test.js   | 210 +++++++++++++++++
 packages/vault/eslint.config.mjs             |  23 ++
 packages/vault/package.json                  |  24 ++
 packages/vault/src/index.js                  |  73 ++++++
 packages/vault/src/items.js                  | 231 ++++++++++++++++++
 packages/vault/src/kdf.js                    | 122 ++++++++++
 packages/vault/src/primitives.js             | 205 ++++++++++++++++
 packages/vault/src/vault-key.js              | 236 +++++++++++++++++++
 packages/vault/vitest.config.js              |  14 ++
 pnpm-lock.yaml                               |  12 +-
 supabase/migrations/20260829120000_vault.sql | 189 +++++++++++++++
 18 files changed, 2421 insertions(+), 3 deletions(-)
 create mode 100644 apps/web/__tests__/vault-validation.test.js
 create mode 100644 apps/web/app/api/vault/items/[id]/route.js
 create mode 100644 apps/web/app/api/vault/items/route.js
 create mode 100644 apps/web/app/api/vault/meta/route.js
 create mode 100644 apps/web/lib/vault-validation.js
 create mode 100644 packages/vault/__tests__/items.test.js
 create mode 100644 packages/vault/__tests__/primitives.test.js
 create mode 100644 packages/vault/__tests__/vault-key.test.js
 create mode 100644 packages/vault/eslint.config.mjs
 create mode 100644 packages/vault/package.json
 create mode 100644 packages/vault/src/index.js
 create mode 100644 packages/vault/src/items.js
 create mode 100644 packages/vault/src/kdf.js
 create mode 100644 packages/vault/src/primitives.js
 create mode 100644 packages/vault/src/vault-key.js
 create mode 100644 packages/vault/vitest.config.js
 create mode 100644 supabase/migrations/20260829120000_vault.sql

diff --git a/apps/web/__tests__/vault-validation.test.js b/apps/web/__tests__/vault-validation.test.js
new file mode 100644
index 0000000..983d1d5
--- /dev/null
+++ b/apps/web/__tests__/vault-validation.test.js
@@ -0,0 +1,155 @@
+/**
+ * Tests for vault payload validation.
+ *
+ * The server cannot inspect what it stores, so these checks are the entire
+ * defence against a malformed or hostile write reaching the table. The
+ * KDF-floor case matters most: it stops one client creating a weak vault that
+ * every other client then has to open.
+ * @module __tests__/vault-validation.test
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  isUuid,
+  isSaneBlob,
+  validateItemPayload,
+  validateVaultMeta,
+  MAX_CIPHERTEXT_LENGTH,
+  MIN_KDF_ITERATIONS,
+} from '@/lib/vault-validation';
+
+const validItem = () => ({
+  id: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
+  type: 1,
+  ciphertext: 'aGVsbG8gd29ybGQ=',
+  iv: 'YWJjZGVmZ2hpams=',
+});
+
+const validMeta = () => ({
+  kdf: 'pbkdf2-sha256',
+  iterations: 600000,
+  salt: 'c2FsdHNhbHQ=',
+  protectedUserKey: 'a2V5',
+  protectedUserKeyIv: 'aXY=',
+  authHash: 'aGFzaA==',
+});
+
+describe('isUuid', () => {
+  it('accepts a v4 uuid', () => {
+    expect(isUuid('3f2504e0-4f89-41d3-9a0c-0305e82c3301')).toBe(true);
+  });
+
+  it.each([['not-a-uuid'], [''], [null], [42], ['3f2504e04f8941d39a0c0305e82c3301']])(
+    'rejects %s',
+    (value) => {
+      expect(isUuid(value)).toBe(false);
+    }
+  );
+});
+
+describe('isSaneBlob', () => {
+  it('accepts base64', () => {
+    expect(isSaneBlob('aGVsbG8=')).toBe(true);
+  });
+
+  it('rejects non-base64 characters', () => {
+    expect(isSaneBlob('not base64!')).toBe(false);
+    expect(isSaneBlob('<script>')).toBe(false);
+  });
+
+  it('rejects anything over the length ceiling', () => {
+    expect(isSaneBlob('a'.repeat(2000))).toBe(false);
+  });
+
+  it('treats an empty value as missing', () => {
+    expect(isSaneBlob('')).toBe(false);
+    expect(isSaneBlob('', { required: false })).toBe(true);
+    expect(isSaneBlob(undefined, { required: false })).toBe(true);
+  });
+});
+
+describe('validateItemPayload', () => {
+  it('accepts a well-formed item', () => {
+    expect(validateItemPayload(validItem())).toBeNull();
+  });
+
+  it('requires a real id', () => {
+    expect(validateItemPayload({ ...validItem(), id: 'nope' })).toMatch(/valid item id/);
+  });
+
+  it('can skip the id, for a route that takes it from the path', () => {
+    const { id: _omitted, ...withoutId } = validItem();
+    expect(validateItemPayload(withoutId, { requireId: false })).toBeNull();
+  });
+
+  it.each([[0], [5], [null], ['login'], [1.5]])('rejects type %s', (type) => {
+    expect(validateItemPayload({ ...validItem(), type })).toMatch(/Unknown item type/);
+  });
+
+  it('accepts every defined type', () => {
+    for (const type of [1, 2, 3, 4]) {
+      expect(validateItemPayload({ ...validItem(), type })).toBeNull();
+    }
+  });
+
+  it('rejects an empty or non-base64 ciphertext', () => {
+    expect(validateItemPayload({ ...validItem(), ciphertext: '' })).toMatch(/ciphertext/);
+    expect(validateItemPayload({ ...validItem(), ciphertext: 'not base64!' })).toMatch(
+      /ciphertext/
+    );
+  });
+
+  it('rejects a ciphertext beyond the size ceiling', () => {
+    const huge = 'a'.repeat(MAX_CIPHERTEXT_LENGTH + 4);
+    expect(validateItemPayload({ ...validItem(), ciphertext: huge })).toMatch(/ciphertext/);
+  });
+
+  it('rejects a malformed iv', () => {
+    expect(validateItemPayload({ ...validItem(), iv: '!!' })).toMatch(/iv/);
+  });
+
+  it('rejects a non-object body', () => {
+    expect(validateItemPayload(null)).toMatch(/Invalid JSON/);
+    expect(validateItemPayload('a string')).toMatch(/Invalid JSON/);
+  });
+});
+
+describe('validateVaultMeta', () => {
+  it('accepts well-formed key material', () => {
+    expect(validateVaultMeta(validMeta())).toBeNull();
+  });
+
+  it('accepts an optional recovery blob', () => {
+    expect(
+      validateVaultMeta({ ...validMeta(), recoveryKeyBlob: 'YmxvYg==', recoveryKeyIv: 'aXY=' })
+    ).toBeNull();
+  });
+
+  it('refuses a KDF it does not know', () => {
+    expect(validateVaultMeta({ ...validMeta(), kdf: 'md5' })).toMatch(/Unsupported KDF/);
+  });
+
+  it('refuses iterations below the floor — the downgrade defence', () => {
+    expect(validateVaultMeta({ ...validMeta(), iterations: 1 })).toMatch(/below the permitted/);
+    expect(validateVaultMeta({ ...validMeta(), iterations: MIN_KDF_ITERATIONS - 1 })).toMatch(
+      /below the permitted/
+    );
+  });
+
+  it('accepts exactly the floor', () => {
+    expect(validateVaultMeta({ ...validMeta(), iterations: MIN_KDF_ITERATIONS })).toBeNull();
+  });
+
+  it('refuses a non-integer iteration count', () => {
+    expect(validateVaultMeta({ ...validMeta(), iterations: '600000' })).toMatch(
+      /below the permitted/
+    );
+  });
+
+  it('requires every mandatory blob', () => {
+    for (const field of ['salt', 'protectedUserKey', 'protectedUserKeyIv', 'authHash']) {
+      const meta = { ...validMeta(), [field]: '' };
+      expect(validateVaultMeta(meta)).toMatch(/Malformed key material/);
+    }
+  });
+});
diff --git a/apps/web/app/api/vault/items/[id]/route.js b/apps/web/app/api/vault/items/[id]/route.js
new file mode 100644
index 0000000..1bf5a75
--- /dev/null
+++ b/apps/web/app/api/vault/items/[id]/route.js
@@ -0,0 +1,181 @@
+/**
+ * PUT    /api/vault/items/[id] - Replace an item's ciphertext
+ * PATCH  /api/vault/items/[id] - Move to trash, or restore from it
+ * DELETE /api/vault/items/[id] - Delete permanently, now
+ *
+ * Authentication: session cookie (web) OR Bearer token (extension)
+ *
+ * PUT takes the revision the client last read. The database bumps `revision` on
+ * every update, so a write built on a stale copy matches no row and comes back
+ * as a 409 rather than silently overwriting whatever another device saved. This
+ * is the reason vault items are one row each instead of a single blob: two
+ * devices editing two different passwords must not cost anyone a credential.
+ */
+
+import { NextResponse } from 'next/server';
+import { corsHeaders, getAuthenticatedUser } from '@/lib/auth-helper';
+import { validateItemPayload, isUuid, TRASH_RETENTION_DAYS } from '@/lib/vault-validation';
+
+const METHODS = ['PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+
+export async function OPTIONS(request) {
+  return new NextResponse(null, { status: 204, headers: corsHeaders(request, METHODS) });
+}
+
+/** Shared preamble: auth, id validation, CORS headers. */
+async function begin(request, context) {
+  const headers = corsHeaders(request, METHODS);
+  const { id } = await context.params;
+
+  if (!isUuid(id)) {
+    return { headers, error: NextResponse.json({ error: 'Invalid item id' }, { status: 400, headers }) };
+  }
+
+  const { user, supabase } = await getAuthenticatedUser(request);
+  if (!user) {
+    return { headers, error: NextResponse.json({ error: 'Unauthorized' }, { status: 401, headers }) };
+  }
+
+  return { headers, id, user, supabase };
+}
+
+/**
+ * Body: { type, ciphertext, iv, revision }
+ */
+export async function PUT(request, context) {
+  const ctx = await begin(request, context);
+  if (ctx.error) return ctx.error;
+  const { headers, id, user, supabase } = ctx;
+
+  try {
+    const body = await request.json().catch(() => null);
+    const invalid = validateItemPayload({ ...body, id }, { requireId: false });
+    if (invalid) {
+      return NextResponse.json({ error: invalid }, { status: 400, headers });
+    }
+    if (!Number.isInteger(body.revision) || body.revision < 1) {
+      return NextResponse.json(
+        { error: 'A revision is required to update an item' },
+        { status: 400, headers }
+      );
+    }
+
+    const { data, error } = await supabase
+      .from('vault_items')
+      .update({ type: body.type, ciphertext: body.ciphertext, iv: body.iv })
+      .eq('id', id)
+      .eq('user_id', user.id)
+      .eq('revision', body.revision)
+      .select('id, type, revision, updated_at')
+      .maybeSingle();
+
+    if (error) {
+      console.error('Vault item update error:', error);
+      return NextResponse.json({ error: 'Failed to update item' }, { status: 500, headers });
+    }
+
+    if (!data) {
+      // Either the item is gone or somebody else wrote first. Return the
+      // current row so the client can merge rather than guess.
+      const { data: current } = await supabase
+        .from('vault_items')
+        .select('id, type, ciphertext, iv, revision, updated_at')
+        .eq('id', id)
+        .eq('user_id', user.id)
+        .maybeSingle();
+
+      if (!current) {
+        return NextResponse.json({ error: 'Item not found' }, { status: 404, headers });
+      }
+      return NextResponse.json(
+        { error: 'Item was modified elsewhere', code: 'REVISION_CONFLICT', item: current },
+        { status: 409, headers }
+      );
+    }
+
+    return NextResponse.json({ item: data }, { headers });
+  } catch (error) {
+    console.error('Vault item API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
+
+/**
+ * Body: { action: 'trash' | 'restore' }
+ */
+export async function PATCH(request, context) {
+  const ctx = await begin(request, context);
+  if (ctx.error) return ctx.error;
+  const { headers, id, user, supabase } = ctx;
+
+  try {
+    const body = await request.json().catch(() => null);
+    const action = body?.action;
+
+    if (action !== 'trash' && action !== 'restore') {
+      return NextResponse.json(
+        { error: "action must be 'trash' or 'restore'" },
+        { status: 400, headers }
+      );
+    }
+
+    const patch =
+      action === 'trash'
+        ? {
+            deleted_at: new Date().toISOString(),
+            purge_after: new Date(
+              Date.now() + TRASH_RETENTION_DAYS * 24 * 60 * 60 * 1000
+            ).toISOString(),
+          }
+        : { deleted_at: null, purge_after: null };
+
+    const { data, error } = await supabase
+      .from('vault_items')
+      .update(patch)
+      .eq('id', id)
+      .eq('user_id', user.id)
+      .select('id, revision, deleted_at, purge_after')
+      .maybeSingle();
+
+    if (error) {
+      console.error('Vault item trash error:', error);
+      return NextResponse.json({ error: `Failed to ${action} item` }, { status: 500, headers });
+    }
+    if (!data) {
+      return NextResponse.json({ error: 'Item not found' }, { status: 404, headers });
+    }
+
+    return NextResponse.json({ item: data }, { headers });
+  } catch (error) {
+    console.error('Vault item API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
+
+/**
+ * Permanent deletion. The trash bin is PATCH { action: 'trash' } — this is the
+ * irreversible one, used by "delete forever" and by emptying the trash.
+ */
+export async function DELETE(request, context) {
+  const ctx = await begin(request, context);
+  if (ctx.error) return ctx.error;
+  const { headers, id, user, supabase } = ctx;
+
+  try {
+    const { error } = await supabase
+      .from('vault_items')
+      .delete()
+      .eq('id', id)
+      .eq('user_id', user.id);
+
+    if (error) {
+      console.error('Vault item delete error:', error);
+      return NextResponse.json({ error: 'Failed to delete item' }, { status: 500, headers });
+    }
+
+    return NextResponse.json({ success: true }, { headers });
+  } catch (error) {
+    console.error('Vault item API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
diff --git a/apps/web/app/api/vault/items/route.js b/apps/web/app/api/vault/items/route.js
new file mode 100644
index 0000000..10c2259
--- /dev/null
+++ b/apps/web/app/api/vault/items/route.js
@@ -0,0 +1,118 @@
+/**
+ * GET  /api/vault/items - List the caller's encrypted items
+ * POST /api/vault/items - Create an item
+ *
+ * Authentication: session cookie (web) OR Bearer token (extension)
+ *
+ * Items are ciphertext to this route. The id is generated by the client because
+ * it is bound into the ciphertext as additional authenticated data, so the
+ * server accepting an id it did not choose is deliberate — see
+ * packages/vault/src/items.js.
+ *
+ * Query parameters:
+ *   ?since=<ISO timestamp>  only items changed since then (incremental sync)
+ *   ?trash=1                the trash bin instead of the active vault
+ */
+
+import { NextResponse } from 'next/server';
+import { corsHeaders, getAuthenticatedUser } from '@/lib/auth-helper';
+import { validateItemPayload, MAX_PAGE_SIZE } from '@/lib/vault-validation';
+
+export async function OPTIONS(request) {
+  return new NextResponse(null, {
+    status: 204,
+    headers: corsHeaders(request, ['GET', 'POST', 'OPTIONS']),
+  });
+}
+
+export async function GET(request) {
+  const headers = corsHeaders(request, ['GET', 'POST', 'OPTIONS']);
+
+  try {
+    const { user, supabase } = await getAuthenticatedUser(request);
+    if (!user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401, headers });
+    }
+
+    const { searchParams } = new URL(request.url);
+    const since = searchParams.get('since');
+    const wantsTrash = searchParams.get('trash') === '1';
+    const limit = Math.min(Number(searchParams.get('limit')) || MAX_PAGE_SIZE, MAX_PAGE_SIZE);
+
+    let query = supabase
+      .from('vault_items')
+      .select('id, type, ciphertext, iv, revision, deleted_at, created_at, updated_at')
+      .eq('user_id', user.id)
+      .order('updated_at', { ascending: false })
+      .limit(limit);
+
+    query = wantsTrash ? query.not('deleted_at', 'is', null) : query.is('deleted_at', null);
+
+    if (since) {
+      const parsed = new Date(since);
+      if (Number.isNaN(parsed.getTime())) {
+        return NextResponse.json({ error: 'Invalid since timestamp' }, { status: 400, headers });
+      }
+      query = query.gt('updated_at', parsed.toISOString());
+    }
+
+    const { data, error } = await query;
+
+    if (error) {
+      console.error('Vault items fetch error:', error);
+      return NextResponse.json({ error: 'Failed to fetch items' }, { status: 500, headers });
+    }
+
+    return NextResponse.json({ items: data || [] }, { headers });
+  } catch (error) {
+    console.error('Vault items API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
+
+/**
+ * Body: { id, type, ciphertext, iv }
+ */
+export async function POST(request) {
+  const headers = corsHeaders(request, ['GET', 'POST', 'OPTIONS']);
+
+  try {
+    const { user, supabase } = await getAuthenticatedUser(request);
+    if (!user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401, headers });
+    }
+
+    const body = await request.json().catch(() => null);
+    const invalid = validateItemPayload(body);
+    if (invalid) {
+      return NextResponse.json({ error: invalid }, { status: 400, headers });
+    }
+
+    const { data, error } = await supabase
+      .from('vault_items')
+      .insert({
+        id: body.id,
+        user_id: user.id,
+        type: body.type,
+        ciphertext: body.ciphertext,
+        iv: body.iv,
+      })
+      .select('id, type, revision, created_at, updated_at')
+      .single();
+
+    if (error) {
+      // A duplicate id means the client already created this item — most often
+      // a retry of a request that in fact succeeded.
+      if (error.code === '23505') {
+        return NextResponse.json({ error: 'Item already exists' }, { status: 409, headers });
+      }
+      console.error('Vault item insert error:', error);
+      return NextResponse.json({ error: 'Failed to create item' }, { status: 500, headers });
+    }
+
+    return NextResponse.json({ item: data }, { status: 201, headers });
+  } catch (error) {
+    console.error('Vault items API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
diff --git a/apps/web/app/api/vault/meta/route.js b/apps/web/app/api/vault/meta/route.js
new file mode 100644
index 0000000..b655dd8
--- /dev/null
+++ b/apps/web/app/api/vault/meta/route.js
@@ -0,0 +1,145 @@
+/**
+ * GET  /api/vault/meta - Fetch the caller's vault key material
+ * POST /api/vault/meta - Create a vault, or re-wrap it after a password change
+ *
+ * Authentication: session cookie (web) OR Bearer token (extension)
+ *
+ * Everything moved through this route is opaque to the server. The wrapped user
+ * key can only be opened by a key derived from the master password, which never
+ * leaves the device — so these handlers deliberately do no validation of the
+ * contents beyond shape and size. There is nothing here for the server to check.
+ *
+ * The KDF parameters are returned to the client so it can reproduce the
+ * derivation. The client refuses to derive below its own floor, so serving
+ * weakened parameters from a compromised server does not buy an attacker a
+ * cheaper offline guess.
+ */
+
+import { NextResponse } from 'next/server';
+import { corsHeaders, getAuthenticatedUser } from '@/lib/auth-helper';
+import { validateVaultMeta } from '@/lib/vault-validation';
+
+export async function OPTIONS(request) {
+  return new NextResponse(null, {
+    status: 204,
+    headers: corsHeaders(request, ['GET', 'POST', 'OPTIONS']),
+  });
+}
+
+export async function GET(request) {
+  const headers = corsHeaders(request, ['GET', 'POST', 'OPTIONS']);
+
+  try {
+    const { user, supabase } = await getAuthenticatedUser(request);
+    if (!user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401, headers });
+    }
+
+    const { data, error } = await supabase
+      .from('vault_meta')
+      .select(
+        'kdf, kdf_iterations, kdf_memory_kib, kdf_parallelism, kdf_salt, ' +
+          'protected_user_key, protected_user_key_iv, recovery_key_blob, recovery_key_iv, created_at'
+      )
+      .eq('user_id', user.id)
+      .maybeSingle();
+
+    if (error) {
+      console.error('Vault meta fetch error:', error);
+      return NextResponse.json({ error: 'Failed to fetch vault' }, { status: 500, headers });
+    }
+
+    // No vault yet is a normal state for every user who has not made one, not
+    // an error — the client uses this to decide between "unlock" and "set up".
+    if (!data) {
+      return NextResponse.json({ exists: false, meta: null }, { headers });
+    }
+
+    return NextResponse.json(
+      {
+        exists: true,
+        meta: {
+          kdf: data.kdf,
+          iterations: data.kdf_iterations,
+          memoryKib: data.kdf_memory_kib,
+          parallelism: data.kdf_parallelism,
+          salt: data.kdf_salt,
+          protectedUserKey: data.protected_user_key,
+          protectedUserKeyIv: data.protected_user_key_iv,
+          recoveryKeyBlob: data.recovery_key_blob,
+          recoveryKeyIv: data.recovery_key_iv,
+          createdAt: data.created_at,
+        },
+      },
+      { headers }
+    );
+  } catch (error) {
+    console.error('Vault meta API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
+
+/**
+ * Body: {
+ *   kdf, iterations, salt, protectedUserKey, protectedUserKeyIv,
+ *   authHash, recoveryKeyBlob?, recoveryKeyIv?
+ * }
+ */
+export async function POST(request) {
+  const headers = corsHeaders(request, ['GET', 'POST', 'OPTIONS']);
+
+  try {
+    const { user, supabase } = await getAuthenticatedUser(request);
+    if (!user) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401, headers });
+    }
+
+    const body = await request.json().catch(() => null);
+    if (!body) {
+      return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400, headers });
+    }
+
+    const invalid = validateVaultMeta(body);
+    if (invalid) {
+      return NextResponse.json({ error: invalid }, { status: 400, headers });
+    }
+
+    const {
+      kdf,
+      iterations,
+      salt,
+      protectedUserKey,
+      protectedUserKeyIv,
+      authHash,
+      recoveryKeyBlob,
+      recoveryKeyIv,
+    } = body;
+
+    const row = {
+      user_id: user.id,
+      kdf,
+      kdf_iterations: iterations,
+      kdf_salt: salt,
+      protected_user_key: protectedUserKey,
+      protected_user_key_iv: protectedUserKeyIv,
+      auth_hash: authHash,
+      recovery_key_blob: recoveryKeyBlob || null,
+      recovery_key_iv: recoveryKeyIv || null,
+      updated_at: new Date().toISOString(),
+    };
+
+    // Upsert covers both creating a vault and re-wrapping it after a password
+    // change. RLS restricts this to the caller's own row either way.
+    const { error } = await supabase.from('vault_meta').upsert(row, { onConflict: 'user_id' });
+
+    if (error) {
+      console.error('Vault meta save error:', error);
+      return NextResponse.json({ error: 'Failed to save vault' }, { status: 500, headers });
+    }
+
+    return NextResponse.json({ success: true }, { headers });
+  } catch (error) {
+    console.error('Vault meta API error:', error);
+    return NextResponse.json({ error: 'Internal server error' }, { status: 500, headers });
+  }
+}
diff --git a/apps/web/lib/vault-validation.js b/apps/web/lib/vault-validation.js
new file mode 100644
index 0000000..9a1bb88
--- /dev/null
+++ b/apps/web/lib/vault-validation.js
@@ -0,0 +1,85 @@
+/**
+ * Shape validation for vault payloads.
+ *
+ * The server cannot inspect what it is storing — that is the point of the
+ * feature — so validation here is limited to what is checkable without a key:
+ * that ids are ids, that blobs are base64, and that nothing is absurdly large.
+ *
+ * Lives outside the route files because a Next.js route module may only export
+ * handlers and route config; anything else fails the build.
+ */
+
+/** A generous ciphertext ceiling: notes are free text, but not unbounded. */
+export const MAX_CIPHERTEXT_LENGTH = 64 * 1024;
+/** Ceiling for key material and IVs. */
+export const MAX_KEY_FIELD_LENGTH = 1024;
+/** Largest page of items returned in one request. */
+export const MAX_PAGE_SIZE = 1000;
+/** How long a deleted item stays recoverable. */
+export const TRASH_RETENTION_DAYS = 30;
+/**
+ * Lowest KDF iteration count the server will store. Mirrors
+ * MIN_PBKDF2_ITERATIONS in packages/vault/src/kdf.js — the client enforces this
+ * for its own safety, and the server enforces it so one client cannot create a
+ * weak vault that every other client then has to open.
+ */
+export const MIN_KDF_ITERATIONS = 100_000;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/** @param {string} value */
+export function isUuid(value) {
+  return typeof value === 'string' && UUID_RE.test(value);
+}
+
+/**
+ * Base64 of a plausible length, and nothing else.
+ * @param {unknown} value
+ * @param {{ required?: boolean, maxLength?: number }} [options]
+ */
+export function isSaneBlob(value, { required = true, maxLength = MAX_KEY_FIELD_LENGTH } = {}) {
+  if (value === undefined || value === null || value === '') return !required;
+  return typeof value === 'string' && value.length <= maxLength && BASE64_RE.test(value);
+}
+
+/**
+ * Validate an item create/update payload.
+ * @param {unknown} body
+ * @param {{ requireId?: boolean }} [options]
+ * @returns {string|null} an error message, or null when the payload is usable
+ */
+export function validateItemPayload(body, { requireId = true } = {}) {
+  if (!body || typeof body !== 'object') return 'Invalid JSON body';
+  if (requireId && !isUuid(body.id)) return 'A valid item id is required';
+  if (!Number.isInteger(body.type) || body.type < 1 || body.type > 4) return 'Unknown item type';
+  if (!isSaneBlob(body.ciphertext, { maxLength: MAX_CIPHERTEXT_LENGTH })) {
+    return 'Malformed ciphertext';
+  }
+  if (!isSaneBlob(body.iv, { maxLength: 64 })) return 'Malformed iv';
+  return null;
+}
+
+/**
+ * Validate the vault key material posted at creation or re-wrap.
+ * @param {unknown} body
+ * @returns {string|null}
+ */
+export function validateVaultMeta(body) {
+  if (!body || typeof body !== 'object') return 'Invalid JSON body';
+  if (body.kdf !== 'pbkdf2-sha256' && body.kdf !== 'argon2id') return 'Unsupported KDF';
+  if (!Number.isInteger(body.iterations) || body.iterations < MIN_KDF_ITERATIONS) {
+    return 'KDF iterations below the permitted minimum';
+  }
+  if (
+    !isSaneBlob(body.salt) ||
+    !isSaneBlob(body.protectedUserKey) ||
+    !isSaneBlob(body.protectedUserKeyIv) ||
+    !isSaneBlob(body.authHash) ||
+    !isSaneBlob(body.recoveryKeyBlob, { required: false }) ||
+    !isSaneBlob(body.recoveryKeyIv, { required: false })
+  ) {
+    return 'Malformed key material';
+  }
+  return null;
+}
diff --git a/packages/vault/__tests__/items.test.js b/packages/vault/__tests__/items.test.js
new file mode 100644
index 0000000..e933d8f
--- /dev/null
+++ b/packages/vault/__tests__/items.test.js
@@ -0,0 +1,220 @@
+/**
+ * Tests for the item record format and its encryption.
+ *
+ * The headline assertion here is the one the whole product claims: nothing a
+ * user typed appears anywhere in what gets sent to the server.
+ * @module __tests__/items.test
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  ITEM_TYPE,
+  ITEM_TYPE_NAME,
+  ITEM_SCHEMA_VERSION,
+  MAX_HISTORY_ENTRIES,
+  createItem,
+  recordPasswordChange,
+  encryptItem,
+  decryptItem,
+  decryptItems,
+} from '../src/items.js';
+import { randomBytes, KEY_BYTES } from '../src/primitives.js';
+
+const userKey = () => randomBytes(KEY_BYTES);
+
+describe('createItem', () => {
+  it('builds a login with every field present', () => {
+    const item = createItem('login', { name: 'GitHub' });
+
+    expect(item.v).toBe(ITEM_SCHEMA_VERSION);
+    expect(item.type).toBe('login');
+    expect(item.name).toBe('GitHub');
+    expect(item.id).toMatch(/^[0-9a-f-]{36}$/);
+    expect(item.login).toEqual({ username: '', password: '', totp: '', uris: [] });
+    expect(item.history).toEqual([]);
+  });
+
+  it('builds cards and identities from the same shape', () => {
+    const card = createItem('card', { card: { number: '4242424242424242' } });
+    expect(card.card.number).toBe('4242424242424242');
+    expect(card.card.cardholderName).toBe('');
+
+    const identity = createItem('identity', { identity: { firstName: 'Ada' } });
+    expect(identity.identity.firstName).toBe('Ada');
+    expect(identity.identity.country).toBe('');
+  });
+
+  it('gives every item a distinct id', () => {
+    const ids = new Set(Array.from({ length: 20 }, () => createItem('login').id));
+    expect(ids.size).toBe(20);
+  });
+
+  it('refuses an unknown type', () => {
+    expect(() => createItem('cryptowallet')).toThrow(/Unknown item type/);
+  });
+
+  it('maps type names to the stored integers both ways', () => {
+    expect(ITEM_TYPE.login).toBe(1);
+    expect(ITEM_TYPE_NAME[ITEM_TYPE.card]).toBe('card');
+  });
+});
+
+describe('encryptItem / decryptItem', () => {
+  it('round-trips every field', async () => {
+    const key = userKey();
+    const item = createItem('login', {
+      name: 'GitHub',
+      notes: 'recovery codes elsewhere',
+      login: {
+        username: 'anthony@profullstack.com',
+        password: 'hunter2',
+        totp: 'otpauth://totp/x',
+        uris: [{ uri: 'https://github.com', match: 'domain' }],
+      },
+    });
+
+    const row = await encryptItem(key, item);
+    expect(await decryptItem(key, row)).toEqual(item);
+  });
+
+  it('sends nothing the user typed — the whole claim, asserted', async () => {
+    const key = userKey();
+    const item = createItem('login', {
+      name: 'My Bank',
+      notes: 'sort code 00-00-00',
+      login: { username: 'anthony@profullstack.com', password: 'hunter2', totp: '', uris: [] },
+    });
+
+    const row = await encryptItem(key, item);
+    const wire = JSON.stringify(row);
+
+    for (const secret of ['hunter2', 'anthony@profullstack.com', 'My Bank', 'sort code']) {
+      expect(wire).not.toContain(secret);
+    }
+    // Only the id, the type number, and two opaque blobs leave the device.
+    expect(Object.keys(row).sort()).toEqual(['ciphertext', 'id', 'iv', 'type']);
+  });
+
+  it('stores the type as a plaintext integer, by design', async () => {
+    const row = await encryptItem(userKey(), createItem('card'));
+    expect(row.type).toBe(ITEM_TYPE.card);
+  });
+
+  it('produces different ciphertext for identical items', async () => {
+    const key = userKey();
+    const item = createItem('login', { name: 'Same' });
+    const a = await encryptItem(key, item);
+    const b = await encryptItem(key, item);
+    expect(a.ciphertext).not.toBe(b.ciphertext);
+  });
+
+  it('cannot be decrypted with a different user key', async () => {
+    const row = await encryptItem(userKey(), createItem('login', { name: 'x' }));
+    await expect(decryptItem(userKey(), row)).rejects.toThrow(/Could not decrypt/);
+  });
+
+  it('refuses a ciphertext moved to a different row id', async () => {
+    const key = userKey();
+    const a = await encryptItem(key, createItem('login', { name: 'low value' }));
+    const b = await encryptItem(key, createItem('login', { name: 'high value' }));
+
+    // Someone with database write access swaps the blobs between rows. The id is
+    // bound into the ciphertext as AAD, so this must fail rather than silently
+    // showing the wrong credential under the wrong name.
+    const swapped = { ...b, ciphertext: a.ciphertext, iv: a.iv };
+    await expect(decryptItem(key, swapped)).rejects.toThrow(/Could not decrypt/);
+  });
+
+  it('refuses a tampered ciphertext', async () => {
+    const key = userKey();
+    const row = await encryptItem(key, createItem('login', { name: 'x' }));
+    const bytes = atob(row.ciphertext).split('');
+    bytes[0] = String.fromCharCode(bytes[0].charCodeAt(0) ^ 0xff);
+    await expect(decryptItem(key, { ...row, ciphertext: btoa(bytes.join('')) })).rejects.toThrow(
+      /Could not decrypt/
+    );
+  });
+
+  it('refuses to encrypt an item with no id', async () => {
+    await expect(encryptItem(userKey(), { type: 'login' })).rejects.toThrow(/must have an id/);
+  });
+});
+
+describe('decryptItems', () => {
+  it('returns the good items and reports the bad ones', async () => {
+    const key = userKey();
+    const good = await encryptItem(key, createItem('login', { name: 'fine' }));
+    const bad = await encryptItem(userKey(), createItem('login', { name: 'other key' }));
+
+    const { items, failed } = await decryptItems(key, [good, bad]);
+
+    // One corrupt row must not hide the rest of the vault.
+    expect(items).toHaveLength(1);
+    expect(items[0].name).toBe('fine');
+    expect(failed).toHaveLength(1);
+    expect(failed[0].id).toBe(bad.id);
+  });
+});
+
+describe('password history', () => {
+  it('keeps the replaced password, not the new one', () => {
+    let item = createItem('login', { login: { password: 'old-one' } });
+    item = recordPasswordChange(item, 'new-one');
+
+    expect(item.login.password).toBe('new-one');
+    expect(item.history).toHaveLength(1);
+    expect(item.history[0].password).toBe('old-one');
+  });
+
+  it('is newest first', () => {
+    let item = createItem('login', { login: { password: 'first' } });
+    item = recordPasswordChange(item, 'second');
+    item = recordPasswordChange(item, 'third');
+
+    expect(item.history.map((h) => h.password)).toEqual(['second', 'first']);
+  });
+
+  it('does not record a no-op change', () => {
+    let item = createItem('login', { login: { password: 'same' } });
+    item = recordPasswordChange(item, 'same');
+    expect(item.history).toHaveLength(0);
+  });
+
+  it('does not record the first password, which replaced nothing', () => {
+    let item = createItem('login');
+    item = recordPasswordChange(item, 'first ever');
+    expect(item.history).toHaveLength(0);
+  });
+
+  it('caps history so the blob cannot grow without bound', () => {
+    let item = createItem('login', { login: { password: 'p0' } });
+    for (let i = 1; i <= MAX_HISTORY_ENTRIES + 10; i++) {
+      item = recordPasswordChange(item, `p${i}`);
+    }
+    expect(item.history).toHaveLength(MAX_HISTORY_ENTRIES);
+    // The most recent replacement survives; the oldest fall off.
+    expect(item.history[0].password).toBe(`p${MAX_HISTORY_ENTRIES + 9}`);
+  });
+
+  it('travels inside the encrypted blob, so it is protected for free', async () => {
+    const key = userKey();
+    let item = createItem('login', { login: { password: 'leaked-if-plaintext' } });
+    item = recordPasswordChange(item, 'current');
+
+    const row = await encryptItem(key, item);
+    expect(JSON.stringify(row)).not.toContain('leaked-if-plaintext');
+
+    const back = await decryptItem(key, row);
+    expect(back.history[0].password).toBe('leaked-if-plaintext');
+  });
+
+  it('is only for logins', () => {
+    expect(() => recordPasswordChange(createItem('card'), 'x')).toThrow(/Only logins/);
+  });
+
+  it('does not mutate the item it was given', () => {
+    const item = createItem('login', { login: { password: 'original' } });
+    recordPasswordChange(item, 'changed');
+    expect(item.login.password).toBe('original');
+  });
+});
diff --git a/packages/vault/__tests__/primitives.test.js b/packages/vault/__tests__/primitives.test.js
new file mode 100644
index 0000000..c0c9f8b
--- /dev/null
+++ b/packages/vault/__tests__/primitives.test.js
@@ -0,0 +1,181 @@
+/**
+ * Known-answer tests for the vault primitives.
+ *
+ * These pin our WebCrypto usage against published RFC vectors, not against our
+ * own output. A round-trip test proves only that we are self-consistent — it
+ * would still pass if the parameters were wrong in both directions. These
+ * vectors are the check that we are computing the algorithm everyone else means.
+ * @module __tests__/primitives.test
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  pbkdf2,
+  hkdf,
+  aesGcmEncrypt,
+  aesGcmDecrypt,
+  randomBytes,
+  toHex,
+  fromHex,
+  toBase64,
+  fromBase64,
+  utf8Encode,
+  utf8Decode,
+  timingSafeEqual,
+  IV_BYTES,
+  KEY_BYTES,
+} from '../src/primitives.js';
+
+describe('PBKDF2-HMAC-SHA256 — RFC 7914 §11 vectors', () => {
+  it('passwd / salt / 1 iteration / 64 bytes', async () => {
+    const out = await pbkdf2('passwd', utf8Encode('salt'), 1, 64);
+    expect(toHex(out)).toBe(
+      '55ac046e56e3089fec1691c22544b605f94185216dde0465e68b9d57c20dacbc' +
+        '49ca9cccf179b645991664b39d77ef317c71b845b1e30bd509112041d3a19783'
+    );
+  });
+
+  it('Password / NaCl / 80000 iterations / 64 bytes', async () => {
+    const out = await pbkdf2('Password', utf8Encode('NaCl'), 80_000, 64);
+    expect(toHex(out)).toBe(
+      '4ddcd8f60b98be21830cee5ef22701f9641a4418d04c0414aeff08876b34ab56' +
+        'a1d425a1225833549adb841b51c9b3176a272bdebba1d078478f62b397f33c8d'
+    );
+  }, 30_000);
+
+  it('refuses a non-positive iteration count rather than doing no work', async () => {
+    await expect(pbkdf2('p', utf8Encode('s'), 0, 32)).rejects.toThrow(/positive integer/);
+  });
+});
+
+describe('HKDF-SHA256 — RFC 5869 vectors', () => {
+  it('A.1: 22-byte IKM with salt and info', async () => {
+    // The RFC's info field is raw bytes and not valid UTF-8, so it is passed
+    // as bytes — through the same hkdf() the vault uses, not a special case.
+    const ikm = fromHex('0b'.repeat(22));
+    const salt = fromHex('000102030405060708090a0b0c');
+    const info = fromHex('f0f1f2f3f4f5f6f7f8f9');
+    const out = await hkdf(ikm, info, 42, salt);
+    expect(toHex(out)).toBe(
+      '3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865'
+    );
+  });
+
+  it('A.3: zero-length salt and info', async () => {
+    const ikm = fromHex('0b'.repeat(22));
+    const out = await hkdf(ikm, '', 42);
+    expect(toHex(out)).toBe(
+      '8da4e775a563c18f715f802a063c5a31b8a11f5c5ee1879ec3454e5f3c738d2d9d201395faa4b61a96c8'
+    );
+  });
+
+  it('different info labels give independent keys from the same input', async () => {
+    const ikm = randomBytes(KEY_BYTES);
+    const a = await hkdf(ikm, 'label:a');
+    const b = await hkdf(ikm, 'label:b');
+    expect(toHex(a)).not.toBe(toHex(b));
+  });
+});
+
+describe('AES-256-GCM', () => {
+  it('round-trips', async () => {
+    const key = randomBytes(KEY_BYTES);
+    const message = utf8Encode('correct horse battery staple');
+    const { iv, ciphertext } = await aesGcmEncrypt(key, message);
+    expect(utf8Decode(await aesGcmDecrypt(key, iv, ciphertext))).toBe(
+      'correct horse battery staple'
+    );
+  });
+
+  it('uses a fresh IV every call — reuse would break the mode', async () => {
+    const key = randomBytes(KEY_BYTES);
+    const message = utf8Encode('same message');
+    const a = await aesGcmEncrypt(key, message);
+    const b = await aesGcmEncrypt(key, message);
+
+    expect(toHex(a.iv)).not.toBe(toHex(b.iv));
+    expect(a.iv).toHaveLength(IV_BYTES);
+    // Identical plaintext must not produce identical ciphertext.
+    expect(toHex(a.ciphertext)).not.toBe(toHex(b.ciphertext));
+  });
+
+  it('rejects a tampered ciphertext instead of returning garbage', async () => {
+    const key = randomBytes(KEY_BYTES);
+    const { iv, ciphertext } = await aesGcmEncrypt(key, utf8Encode('secret'));
+    ciphertext[0] ^= 0xff;
+    await expect(aesGcmDecrypt(key, iv, ciphertext)).rejects.toThrow();
+  });
+
+  it('rejects the wrong key', async () => {
+    const { iv, ciphertext } = await aesGcmEncrypt(randomBytes(KEY_BYTES), utf8Encode('secret'));
+    await expect(aesGcmDecrypt(randomBytes(KEY_BYTES), iv, ciphertext)).rejects.toThrow();
+  });
+
+  it('binds additional authenticated data', async () => {
+    const key = randomBytes(KEY_BYTES);
+    const aad = utf8Encode('row-id-1');
+    const { iv, ciphertext } = await aesGcmEncrypt(key, utf8Encode('secret'), aad);
+
+    // Correct AAD decrypts.
+    expect(utf8Decode(await aesGcmDecrypt(key, iv, ciphertext, aad))).toBe('secret');
+    // A different AAD does not — this is what stops a ciphertext being moved
+    // from one row to another.
+    await expect(aesGcmDecrypt(key, iv, ciphertext, utf8Encode('row-id-2'))).rejects.toThrow();
+  });
+
+  it('refuses a key of the wrong length', async () => {
+    await expect(aesGcmEncrypt(randomBytes(16), utf8Encode('x'))).rejects.toThrow(/32 bytes/);
+  });
+});
+
+describe('encoding helpers', () => {
+  it('base64 round-trips arbitrary bytes', () => {
+    const bytes = randomBytes(64);
+    expect(toHex(fromBase64(toBase64(bytes)))).toBe(toHex(bytes));
+  });
+
+  it('handles high bytes that a naive string conversion would mangle', () => {
+    const bytes = new Uint8Array([0, 1, 127, 128, 200, 254, 255]);
+    expect(Array.from(fromBase64(toBase64(bytes)))).toEqual(Array.from(bytes));
+  });
+
+  it('hex round-trips and ignores separators', () => {
+    const bytes = randomBytes(20);
+    const grouped = (toHex(bytes).match(/.{1,5}/g) || []).join('-').toUpperCase();
+    expect(toHex(fromHex(grouped))).toBe(toHex(bytes));
+  });
+
+  it('rejects odd-length hex', () => {
+    expect(() => fromHex('abc')).toThrow(/even length/);
+  });
+});
+
+describe('timingSafeEqual', () => {
+  it('is true only for identical arrays', () => {
+    expect(timingSafeEqual(fromHex('00ff'), fromHex('00ff'))).toBe(true);
+    expect(timingSafeEqual(fromHex('00ff'), fromHex('00fe'))).toBe(false);
+  });
+
+  it('is false for different lengths', () => {
+    expect(timingSafeEqual(fromHex('00ff'), fromHex('00'))).toBe(false);
+  });
+
+  it('compares every byte rather than stopping at the first difference', () => {
+    // Differing in the first byte and in the last must both be false; a
+    // short-circuiting implementation passes this too, but it documents intent
+    // alongside the constant-time loop.
+    expect(timingSafeEqual(fromHex('ff0000'), fromHex('000000'))).toBe(false);
+    expect(timingSafeEqual(fromHex('0000ff'), fromHex('000000'))).toBe(false);
+  });
+});
+
+describe('randomBytes', () => {
+  it('returns the requested length', () => {
+    expect(randomBytes(32)).toHaveLength(32);
+  });
+
+  it('does not repeat', () => {
+    const seen = new Set(Array.from({ length: 50 }, () => toHex(randomBytes(16))));
+    expect(seen.size).toBe(50);
+  });
+});
diff --git a/packages/vault/__tests__/vault-key.test.js b/packages/vault/__tests__/vault-key.test.js
new file mode 100644
index 0000000..e848929
--- /dev/null
+++ b/packages/vault/__tests__/vault-key.test.js
@@ -0,0 +1,210 @@
+/**
+ * Tests for the vault key lifecycle — creation, unlock, recovery, password
+ * change — and for the properties the whole design rests on.
+ * @module __tests__/vault-key.test
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createVault,
+  unlockVault,
+  unlockWithRecoveryKey,
+  rewrapUserKey,
+  resetRecoveryKey,
+  formatRecoveryKey,
+  parseRecoveryKey,
+  RECOVERY_KEY_BYTES,
+  SALT_BYTES,
+} from '../src/vault-key.js';
+import { toHex, randomBytes, fromBase64 } from '../src/primitives.js';
+import { DEFAULT_KDF_PARAMS, MIN_PBKDF2_ITERATIONS, KDF } from '../src/kdf.js';
+
+// A weak-but-legal KDF setting keeps these tests fast. 600k iterations is the
+// shipping default; running it in every test would add minutes.
+const FAST = { kdf: KDF.PBKDF2_SHA256, iterations: MIN_PBKDF2_ITERATIONS };
+const PASSWORD = 'correct horse battery staple';
+
+describe('createVault', () => {
+  it('returns metadata that is safe to send, and keys that are not', async () => {
+    const { meta, userKey, recoveryKey } = await createVault(PASSWORD, { params: FAST });
+
+    expect(meta.kdf).toBe(KDF.PBKDF2_SHA256);
+    expect(meta.iterations).toBe(FAST.iterations);
+    expect(fromBase64(meta.salt)).toHaveLength(SALT_BYTES);
+    expect(meta.protectedUserKey).toBeTruthy();
+    expect(meta.authHash).toBeTruthy();
+    expect(userKey).toHaveLength(32);
+    expect(recoveryKey).toMatch(/^[0-9A-F-]+$/);
+  });
+
+  it('never puts the password, or the user key, in the metadata', async () => {
+    const { meta, userKey } = await createVault(PASSWORD, { params: FAST });
+    const serialized = JSON.stringify(meta);
+
+    expect(serialized).not.toContain(PASSWORD);
+    expect(serialized).not.toContain(toHex(userKey));
+  });
+
+  it('gives two vaults with the same password different keys and salts', async () => {
+    const a = await createVault(PASSWORD, { params: FAST });
+    const b = await createVault(PASSWORD, { params: FAST });
+
+    expect(a.meta.salt).not.toBe(b.meta.salt);
+    expect(a.meta.authHash).not.toBe(b.meta.authHash);
+    expect(toHex(a.userKey)).not.toBe(toHex(b.userKey));
+  });
+
+  it('refuses an empty password', async () => {
+    await expect(createVault('', { params: FAST })).rejects.toThrow(/master password is required/);
+  });
+});
+
+describe('unlockVault', () => {
+  it('recovers exactly the same user key', async () => {
+    const { meta, userKey } = await createVault(PASSWORD, { params: FAST });
+    const unlocked = await unlockVault(PASSWORD, meta);
+    expect(toHex(unlocked.userKey)).toBe(toHex(userKey));
+  });
+
+  it('produces the same auth hash the server was given', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    const unlocked = await unlockVault(PASSWORD, meta);
+    expect(unlocked.authHash).toBe(meta.authHash);
+  });
+
+  it('rejects the wrong password without leaking why', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    await expect(unlockVault('wrong password', meta)).rejects.toThrow('Incorrect password');
+  });
+
+  it('rejects a tampered wrapped key', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    const bytes = fromBase64(meta.protectedUserKey);
+    bytes[0] ^= 0xff;
+    const tampered = { ...meta, protectedUserKey: btoa(String.fromCharCode(...bytes)) };
+    await expect(unlockVault(PASSWORD, tampered)).rejects.toThrow('Incorrect password');
+  });
+});
+
+describe('KDF downgrade defence', () => {
+  it('refuses metadata that asks for a trivial iteration count', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    // A compromised server serving iterations: 1 would make every captured auth
+    // hash cheap to attack offline.
+    const downgraded = { ...meta, iterations: 1 };
+    await expect(unlockVault(PASSWORD, downgraded)).rejects.toThrow(/minimum is/);
+  });
+
+  it('refuses an unknown KDF rather than guessing', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    await expect(unlockVault(PASSWORD, { ...meta, kdf: 'md5-lol' })).rejects.toThrow(
+      /Unsupported KDF/
+    );
+  });
+
+  it('refuses to create a vault with weak parameters in the first place', async () => {
+    await expect(
+      createVault(PASSWORD, { params: { kdf: KDF.PBKDF2_SHA256, iterations: 10 } })
+    ).rejects.toThrow(/minimum is/);
+  });
+
+  it('the shipping default is at or above the OWASP floor', () => {
+    expect(DEFAULT_KDF_PARAMS.iterations).toBeGreaterThanOrEqual(600_000);
+  });
+});
+
+describe('recovery key', () => {
+  it('unlocks the vault when the password is forgotten', async () => {
+    const { meta, userKey, recoveryKey } = await createVault(PASSWORD, { params: FAST });
+    const recovered = await unlockWithRecoveryKey(recoveryKey, meta);
+    expect(toHex(recovered.userKey)).toBe(toHex(userKey));
+  });
+
+  it('accepts the key back in any casing, with or without dashes', async () => {
+    const { meta, userKey, recoveryKey } = await createVault(PASSWORD, { params: FAST });
+    const messy = recoveryKey.toLowerCase().replace(/-/g, ' ');
+    const recovered = await unlockWithRecoveryKey(messy, meta);
+    expect(toHex(recovered.userKey)).toBe(toHex(userKey));
+  });
+
+  it('rejects a wrong recovery key', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    const wrong = formatRecoveryKey(randomBytes(RECOVERY_KEY_BYTES));
+    await expect(unlockWithRecoveryKey(wrong, meta)).rejects.toThrow('Incorrect recovery key');
+  });
+
+  it('rejects something that is not a recovery key at all', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    await expect(unlockWithRecoveryKey('hunter2', meta)).rejects.toThrow(/does not look like/);
+  });
+
+  it('round-trips through its written-down form', () => {
+    const bytes = randomBytes(RECOVERY_KEY_BYTES);
+    expect(toHex(parseRecoveryKey(formatRecoveryKey(bytes)))).toBe(toHex(bytes));
+  });
+
+  it('resetting it invalidates the old one and keeps the same vault', async () => {
+    const { meta, userKey, recoveryKey } = await createVault(PASSWORD, { params: FAST });
+    const reset = await resetRecoveryKey(userKey, meta);
+
+    expect(toHex((await unlockWithRecoveryKey(reset.recoveryKey, reset.meta)).userKey)).toBe(
+      toHex(userKey)
+    );
+    await expect(unlockWithRecoveryKey(recoveryKey, reset.meta)).rejects.toThrow(
+      'Incorrect recovery key'
+    );
+  });
+});
+
+describe('changing the master password', () => {
+  it('keeps the same user key, so no item needs re-encrypting', async () => {
+    const { meta, userKey } = await createVault(PASSWORD, { params: FAST });
+    const { meta: next } = await rewrapUserKey(userKey, 'a brand new password', meta, {
+      params: FAST,
+    });
+
+    const unlocked = await unlockVault('a brand new password', next);
+    expect(toHex(unlocked.userKey)).toBe(toHex(userKey));
+  });
+
+  it('stops the old password working', async () => {
+    const { meta, userKey } = await createVault(PASSWORD, { params: FAST });
+    const { meta: next } = await rewrapUserKey(userKey, 'a brand new password', meta, {
+      params: FAST,
+    });
+    await expect(unlockVault(PASSWORD, next)).rejects.toThrow('Incorrect password');
+  });
+
+  it('issues a fresh salt and auth hash', async () => {
+    const { meta, userKey } = await createVault(PASSWORD, { params: FAST });
+    const { meta: next } = await rewrapUserKey(userKey, 'another password', meta, { params: FAST });
+
+    expect(next.salt).not.toBe(meta.salt);
+    expect(next.authHash).not.toBe(meta.authHash);
+  });
+
+  it('preserves the recovery key, which still opens the vault', async () => {
+    const { meta, userKey, recoveryKey } = await createVault(PASSWORD, { params: FAST });
+    const { meta: next } = await rewrapUserKey(userKey, 'another password', meta, { params: FAST });
+
+    const recovered = await unlockWithRecoveryKey(recoveryKey, next);
+    expect(toHex(recovered.userKey)).toBe(toHex(userKey));
+  });
+
+  it('upgrades the KDF parameters on the way through', async () => {
+    const { meta, userKey } = await createVault(PASSWORD, { params: FAST });
+    expect(meta.iterations).toBe(FAST.iterations);
+
+    // No params argument means "current defaults" — how a vault created under
+    // weaker settings gets stronger without anyone migrating data.
+    const { meta: next } = await rewrapUserKey(userKey, PASSWORD, meta);
+    expect(next.iterations).toBe(DEFAULT_KDF_PARAMS.iterations);
+  }, 30_000);
+
+  it('refuses a user key that is not a real key', async () => {
+    const { meta } = await createVault(PASSWORD, { params: FAST });
+    await expect(rewrapUserKey(randomBytes(16), 'x', meta, { params: FAST })).rejects.toThrow(
+      /valid unlocked user key/
+    );
+  });
+});
diff --git a/packages/vault/eslint.config.mjs b/packages/vault/eslint.config.mjs
new file mode 100644
index 0000000..2159e15
--- /dev/null
+++ b/packages/vault/eslint.config.mjs
@@ -0,0 +1,23 @@
+import js from "@eslint/js";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+        ...globals.es2024,
+      },
+    },
+    rules: {
+      "no-unused-vars": ["warn", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],
+      "no-console": "off",
+    },
+  },
+  {
+    ignores: ["**/node_modules/**", "**/dist/**", "**/coverage/**"],
+  },
+];
diff --git a/packages/vault/package.json b/packages/vault/package.json
new file mode 100644
index 0000000..9771489
--- /dev/null
+++ b/packages/vault/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "@marksyncr/vault",
+  "version": "0.8.33",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./primitives": "./src/primitives.js",
+    "./kdf": "./src/kdf.js",
+    "./keys": "./src/vault-key.js",
+    "./items": "./src/items.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist coverage"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8"
+  }
+}
diff --git a/packages/vault/src/index.js b/packages/vault/src/index.js
new file mode 100644
index 0000000..bc2ab79
--- /dev/null
+++ b/packages/vault/src/index.js
@@ -0,0 +1,73 @@
+/**
+ * @marksyncr/vault — end-to-end encrypted vault core.
+ *
+ * Shared by the web app and the extension. Every value that reaches the server
+ * has already passed through this package; nothing here sends anything anywhere,
+ * which is what makes "the server cannot read the vault" a property of the code
+ * rather than a promise in the marketing copy.
+ *
+ * Typical use:
+ *
+ *   const { meta, userKey, recoveryKey } = await createVault(password);
+ *   //  POST meta  ->  /api/vault/meta          (safe to send)
+ *   //  show recoveryKey to the user, exactly once
+ *
+ *   const item = createItem('login', { name: 'GitHub', login: { username, password } });
+ *   const row  = await encryptItem(userKey, item);
+ *   //  POST row   ->  /api/vault/items         (ciphertext only)
+ */
+
+export {
+  IV_BYTES,
+  KEY_BYTES,
+  randomBytes,
+  utf8Encode,
+  utf8Decode,
+  toBase64,
+  fromBase64,
+  toHex,
+  fromHex,
+  timingSafeEqual,
+  pbkdf2,
+  hkdf,
+  aesGcmEncrypt,
+  aesGcmDecrypt,
+} from './primitives.js';
+
+export {
+  KDF,
+  DEFAULT_KDF_PARAMS,
+  MIN_PBKDF2_ITERATIONS,
+  INFO_WRAP,
+  INFO_AUTH,
+  INFO_RECOVERY,
+  assertUsableKdfParams,
+  deriveMasterKey,
+  deriveWrapKey,
+  deriveAuthHash,
+  deriveAll,
+} from './kdf.js';
+
+export {
+  SALT_BYTES,
+  RECOVERY_KEY_BYTES,
+  formatRecoveryKey,
+  parseRecoveryKey,
+  createVault,
+  unlockVault,
+  unlockWithRecoveryKey,
+  rewrapUserKey,
+  resetRecoveryKey,
+} from './vault-key.js';
+
+export {
+  ITEM_TYPE,
+  ITEM_TYPE_NAME,
+  ITEM_SCHEMA_VERSION,
+  MAX_HISTORY_ENTRIES,
+  createItem,
+  recordPasswordChange,
+  encryptItem,
+  decryptItem,
+  decryptItems,
+} from './items.js';
diff --git a/packages/vault/src/items.js b/packages/vault/src/items.js
new file mode 100644
index 0000000..500f7cd
--- /dev/null
+++ b/packages/vault/src/items.js
@@ -0,0 +1,231 @@
+/**
+ * Vault items: the record format, and encrypting it under the user key.
+ *
+ * Logins, cards and identities are not three features — they are one record
+ * with a `type` and three field groups. Everything the user typed lives inside
+ * a single encrypted blob, which is what makes password history free: it is an
+ * array in that blob, so it is encrypted by construction rather than needing
+ * its own protected table.
+ */
+
+import {
+  aesGcmEncrypt,
+  aesGcmDecrypt,
+  toBase64,
+  fromBase64,
+  utf8Encode,
+  utf8Decode,
+} from './primitives.js';
+
+/**
+ * Stored in the `type` column in plaintext so the server can filter and
+ * paginate without decrypting. This is deliberate, and it is the metadata the
+ * design accepts leaking: the server learns you hold 40 logins and 2 cards,
+ * never which sites or what values.
+ */
+export const ITEM_TYPE = Object.freeze({
+  login: 1,
+  card: 2,
+  identity: 3,
+  note: 4,
+});
+
+/** Reverse lookup, for turning a stored row back into a name. */
+export const ITEM_TYPE_NAME = Object.freeze(
+  Object.fromEntries(Object.entries(ITEM_TYPE).map(([name, id]) => [id, name]))
+);
+
+/**
+ * Version stamped into every blob. A record you cannot identify is a record you
+ * cannot migrate, so this is written from the first commit rather than added
+ * when it is first needed.
+ */
+export const ITEM_SCHEMA_VERSION = 1;
+
+/**
+ * Password history cap. The blob is rewritten on every save, so an uncapped
+ * array grows the ciphertext without bound.
+ */
+export const MAX_HISTORY_ENTRIES = 20;
+
+/** Empty field groups, so every item has a predictable shape. */
+const EMPTY_FIELDS = Object.freeze({
+  login: () => ({ username: '', password: '', totp: '', uris: [] }),
+  card: () => ({ cardholderName: '', brand: '', number: '', expMonth: '', expYear: '', code: '' }),
+  identity: () => ({
+    title: '',
+    firstName: '',
+    middleName: '',
+    lastName: '',
+    company: '',
+    email: '',
+    phone: '',
+    address1: '',
+    address2: '',
+    city: '',
+    state: '',
+    postalCode: '',
+    country: '',
+  }),
+  note: () => ({}),
+});
+
+/**
+ * Create a new item.
+ *
+ * The id is generated here, on the client, because it is bound into the
+ * ciphertext as additional authenticated data — see {@link encryptItem}. The
+ * server stores this id rather than assigning one.
+ *
+ * @param {keyof ITEM_TYPE} type
+ * @param {Object} [fields] partial item to merge over the defaults
+ * @returns {Object} a plaintext item
+ */
+export function createItem(type, fields = {}) {
+  if (!(type in ITEM_TYPE)) {
+    throw new Error(`Unknown item type: ${type}`);
+  }
+  const now = new Date().toISOString();
+  return {
+    v: ITEM_SCHEMA_VERSION,
+    id: globalThis.crypto.randomUUID(),
+    type,
+    name: '',
+    favorite: false,
+    folderId: null,
+    notes: '',
+    [type]: { ...EMPTY_FIELDS[type](), ...(fields[type] || {}) },
+    history: [],
+    createdAt: now,
+    updatedAt: now,
+    ...stripGroups(fields),
+  };
+}
+
+/** Copy the top-level fields of a partial item, minus the per-type groups. */
+function stripGroups(fields) {
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (key in ITEM_TYPE || key === 'v' || key === 'id') continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Record a password change in the item's own history.
+ *
+ * Called before overwriting the password, so the value being replaced is what
+ * gets kept. Returns a new item; does not mutate.
+ *
+ * @param {Object} item
+ * @param {string} newPassword
+ * @returns {Object}
+ */
+export function recordPasswordChange(item, newPassword) {
+  if (item.type !== 'login') {
+    throw new Error('Only logins have password history');
+  }
+  const previous = item.login?.password || '';
+  const history =
+    previous && previous !== newPassword
+      ? [{ password: previous, changedAt: new Date().toISOString() }, ...(item.history || [])]
+      : [...(item.history || [])];
+
+  return {
+    ...item,
+    login: { ...item.login, password: newPassword },
+    history: history.slice(0, MAX_HISTORY_ENTRIES),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * The additional authenticated data bound to an item's ciphertext.
+ *
+ * Binding the id means a ciphertext cannot be moved from one row to another
+ * without decryption failing — without it, anyone with database write access
+ * could swap the ciphertext of a low-value login into a high-value one and
+ * watch what the user does next.
+ * @param {string} id
+ * @param {number} version
+ */
+function itemAad(id, version) {
+  return utf8Encode(`marksyncr:vault:item:${version}:${id}`);
+}
+
+/**
+ * Encrypt an item for storage.
+ * @param {Uint8Array} userKey
+ * @param {Object} item
+ * @returns {Promise<{ id: string, type: number, ciphertext: string, iv: string }>}
+ */
+export async function encryptItem(userKey, item) {
+  if (!item?.id) throw new Error('An item must have an id before it can be encrypted');
+  if (!(item.type in ITEM_TYPE)) throw new Error(`Unknown item type: ${item.type}`);
+
+  const version = item.v ?? ITEM_SCHEMA_VERSION;
+  const plaintext = utf8Encode(JSON.stringify({ ...item, v: version }));
+  const { iv, ciphertext } = await aesGcmEncrypt(userKey, plaintext, itemAad(item.id, version));
+
+  return {
+    id: item.id,
+    type: ITEM_TYPE[item.type],
+    ciphertext: toBase64(ciphertext),
+    iv: toBase64(iv),
+  };
+}
+
+/**
+ * Decrypt a stored row back into an item.
+ *
+ * Throws when the key is wrong, the ciphertext was altered, or the row's id
+ * does not match the one bound at encryption time.
+ *
+ * @param {Uint8Array} userKey
+ * @param {{ id: string, ciphertext: string, iv: string, v?: number }} row
+ * @returns {Promise<Object>}
+ */
+export async function decryptItem(userKey, row) {
+  const version = row.v ?? ITEM_SCHEMA_VERSION;
+  let plaintext;
+  try {
+    plaintext = await aesGcmDecrypt(
+      userKey,
+      fromBase64(row.iv),
+      fromBase64(row.ciphertext),
+      itemAad(row.id, version)
+    );
+  } catch {
+    throw new Error(`Could not decrypt item ${row.id}`);
+  }
+
+  const item = JSON.parse(utf8Decode(plaintext));
+  if (item.id !== row.id) {
+    // Belt and braces: the AAD already makes this unreachable.
+    throw new Error(`Item id mismatch for ${row.id}`);
+  }
+  return item;
+}
+
+/**
+ * Decrypt a page of rows, keeping going when one fails.
+ *
+ * A single corrupt row must not hide the rest of someone's vault, so failures
+ * are collected and returned rather than thrown.
+ * @param {Uint8Array} userKey
+ * @param {Array<Object>} rows
+ * @returns {Promise<{ items: Object[], failed: Array<{id: string, error: string}> }>}
+ */
+export async function decryptItems(userKey, rows) {
+  const items = [];
+  const failed = [];
+  for (const row of rows) {
+    try {
+      items.push(await decryptItem(userKey, row));
+    } catch (err) {
+      failed.push({ id: row.id, error: err.message });
+    }
+  }
+  return { items, failed };
+}
diff --git a/packages/vault/src/kdf.js b/packages/vault/src/kdf.js
new file mode 100644
index 0000000..cb2a460
--- /dev/null
+++ b/packages/vault/src/kdf.js
@@ -0,0 +1,122 @@
+/**
+ * Key derivation for the MarkSyncr vault.
+ *
+ * The master password is stretched once into a master key, and everything else
+ * is derived from that by HKDF with a distinct label. The labels are versioned
+ * because they are baked into every existing vault — changing a label string
+ * makes every vault in the world undecryptable, so they must never be edited,
+ * only superseded.
+ */
+
+import { pbkdf2, hkdf, toBase64, KEY_BYTES } from './primitives.js';
+
+/** Supported key derivation functions. */
+export const KDF = {
+  PBKDF2_SHA256: 'pbkdf2-sha256',
+  // Reserved. Argon2id needs WASM in the browser, which means adding
+  // 'wasm-unsafe-eval' to the extension CSP. The parameters are carried per-user
+  // in vault_meta specifically so this can be adopted later without
+  // invalidating a single existing vault.
+  ARGON2ID: 'argon2id',
+};
+
+/**
+ * Default parameters for a vault created today. OWASP's current floor for
+ * PBKDF2-HMAC-SHA256 is 600,000 iterations.
+ */
+export const DEFAULT_KDF_PARAMS = Object.freeze({
+  kdf: KDF.PBKDF2_SHA256,
+  iterations: 600_000,
+});
+
+/**
+ * The lowest iteration count a client will accept.
+ *
+ * KDF parameters arrive from the server, which makes them attacker-controlled if
+ * the server is compromised: serving `iterations: 1` would turn every captured
+ * auth hash into an offline guessing exercise with no work factor. Refuse to
+ * derive at all below this floor rather than silently doing weak work.
+ */
+export const MIN_PBKDF2_ITERATIONS = 100_000;
+
+/** Domain-separation labels. Append-only — never edit an existing value. */
+export const INFO_WRAP = 'marksyncr:vault:wrap:v1';
+export const INFO_AUTH = 'marksyncr:vault:auth:v1';
+export const INFO_RECOVERY = 'marksyncr:vault:recovery:v1';
+
+/**
+ * Validate KDF parameters received from the server.
+ * @param {{kdf: string, iterations: number}} params
+ * @returns {{kdf: string, iterations: number}}
+ */
+export function assertUsableKdfParams(params) {
+  const kdf = params?.kdf;
+  if (kdf !== KDF.PBKDF2_SHA256) {
+    throw new Error(`Unsupported KDF: ${kdf ?? 'missing'}`);
+  }
+  const iterations = params?.iterations;
+  if (!Number.isInteger(iterations) || iterations < MIN_PBKDF2_ITERATIONS) {
+    throw new Error(
+      `Refusing to derive a key with ${iterations} iterations — the minimum is ${MIN_PBKDF2_ITERATIONS}`
+    );
+  }
+  return { kdf, iterations };
+}
+
+/**
+ * Stretch the master password into the master key.
+ *
+ * The master key is never used to encrypt anything directly; it exists only to
+ * be split by {@link deriveWrapKey} and {@link deriveAuthHash}.
+ *
+ * @param {string} password
+ * @param {Uint8Array} salt per-user, random, stored alongside the vault
+ * @param {{kdf: string, iterations: number}} params
+ * @returns {Promise<Uint8Array>} 32 bytes
+ */
+export async function deriveMasterKey(password, salt, params = DEFAULT_KDF_PARAMS) {
+  if (typeof password !== 'string' || password.length === 0) {
+    throw new Error('A master password is required');
+  }
+  if (!(salt instanceof Uint8Array) || salt.length < 16) {
+    throw new Error('KDF salt must be at least 16 bytes');
+  }
+  const { iterations } = assertUsableKdfParams(params);
+  return pbkdf2(password, salt, iterations, KEY_BYTES);
+}
+
+/**
+ * The key that wraps the user key. Never leaves the device.
+ * @param {Uint8Array} masterKey
+ * @returns {Promise<Uint8Array>}
+ */
+export function deriveWrapKey(masterKey) {
+  return hkdf(masterKey, INFO_WRAP, KEY_BYTES);
+}
+
+/**
+ * The only password-derived value that is ever sent to the server, which stores
+ * it hashed again. Because it comes out of a different HKDF label than the
+ * wrapping key, holding it does not help an attacker decrypt anything.
+ * @param {Uint8Array} masterKey
+ * @returns {Promise<string>} base64
+ */
+export async function deriveAuthHash(masterKey) {
+  return toBase64(await hkdf(masterKey, INFO_AUTH, KEY_BYTES));
+}
+
+/**
+ * Derive both halves at once — the common path on unlock.
+ * @param {string} password
+ * @param {Uint8Array} salt
+ * @param {{kdf: string, iterations: number}} params
+ * @returns {Promise<{ masterKey: Uint8Array, wrapKey: Uint8Array, authHash: string }>}
+ */
+export async function deriveAll(password, salt, params = DEFAULT_KDF_PARAMS) {
+  const masterKey = await deriveMasterKey(password, salt, params);
+  const [wrapKey, authHash] = await Promise.all([
+    deriveWrapKey(masterKey),
+    deriveAuthHash(masterKey),
+  ]);
+  return { masterKey, wrapKey, authHash };
+}
diff --git a/packages/vault/src/primitives.js b/packages/vault/src/primitives.js
new file mode 100644
index 0000000..aa61b01
--- /dev/null
+++ b/packages/vault/src/primitives.js
@@ -0,0 +1,205 @@
+/**
+ * Cryptographic primitives for the MarkSyncr vault.
+ *
+ * Deliberately thin wrappers over WebCrypto and nothing else. Every function
+ * here is a named algorithm with published test vectors, so the whole file can
+ * be checked against those vectors rather than reasoned about. Nothing in the
+ * vault may implement a construction that is not in this file.
+ *
+ * Runs unmodified in the extension service worker, the browser page and Node 18+,
+ * all of which expose `globalThis.crypto.subtle`.
+ */
+
+/** @returns {SubtleCrypto} */
+function subtle() {
+  const c = globalThis.crypto;
+  if (!c?.subtle) {
+    throw new Error('WebCrypto is unavailable — the vault cannot operate without it');
+  }
+  return c.subtle;
+}
+
+/** AES-GCM initialisation vector length, in bytes. 96 bits is the spec-recommended size. */
+export const IV_BYTES = 12;
+/** Symmetric key length, in bytes. */
+export const KEY_BYTES = 32;
+
+/**
+ * Cryptographically secure random bytes.
+ * @param {number} length
+ * @returns {Uint8Array}
+ */
+export function randomBytes(length) {
+  const out = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(out);
+  return out;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** @param {string} text @returns {Uint8Array} */
+export function utf8Encode(text) {
+  return encoder.encode(text);
+}
+
+/** @param {Uint8Array} bytes @returns {string} */
+export function utf8Decode(bytes) {
+  return decoder.decode(bytes);
+}
+
+/**
+ * Base64 encode. Used for every value that crosses the wire or lands in a
+ * text column — the API speaks JSON, so raw bytes need an encoding.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function toBase64(bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+
+/**
+ * @param {string} b64
+ * @returns {Uint8Array}
+ */
+export function fromBase64(b64) {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+/** @param {Uint8Array} bytes @returns {string} lowercase hex */
+export function toHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** @param {string} hex @returns {Uint8Array} */
+export function fromHex(hex) {
+  const clean = String(hex).replace(/[^0-9a-fA-F]/g, '');
+  if (clean.length % 2 !== 0) throw new Error('Hex string must have an even length');
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(clean.substr(i * 2, 2), 16);
+  return out;
+}
+
+/**
+ * Compare two byte arrays without leaking their contents through timing.
+ *
+ * A plain `===` on hex strings short-circuits at the first differing byte, which
+ * tells an attacker who can time the comparison how much of their guess was
+ * right. Always use this for anything secret-derived.
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {boolean}
+ */
+export function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/**
+ * PBKDF2-HMAC-SHA256.
+ *
+ * This is the slow step that stands between a stolen database and a user's
+ * vault, so the iteration count is a security parameter, not a tuning knob.
+ * @param {string} password
+ * @param {Uint8Array} salt
+ * @param {number} iterations
+ * @param {number} lengthBytes
+ * @returns {Promise<Uint8Array>}
+ */
+export async function pbkdf2(password, salt, iterations, lengthBytes = KEY_BYTES) {
+  if (!Number.isInteger(iterations) || iterations < 1) {
+    throw new Error('PBKDF2 iterations must be a positive integer');
+  }
+  const keyMaterial = await subtle().importKey('raw', utf8Encode(password), 'PBKDF2', false, [
+    'deriveBits',
+  ]);
+  const bits = await subtle().deriveBits(
+    { name: 'PBKDF2', salt, iterations, hash: 'SHA-256' },
+    keyMaterial,
+    lengthBytes * 8
+  );
+  return new Uint8Array(bits);
+}
+
+/**
+ * HKDF-SHA256 expand. Splits one high-entropy key into several independent
+ * keys, one per `info` label — so the wrapping key and the auth hash cannot be
+ * derived from one another.
+ * @param {Uint8Array} ikm  input key material (already high-entropy)
+ * @param {string|Uint8Array} info  domain separation label. Accepts raw bytes as
+ *   well as a string so published test vectors, whose info fields are not valid
+ *   UTF-8, can be checked through this same function rather than a special case.
+ * @param {number} lengthBytes
+ * @param {Uint8Array} [salt]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function hkdf(ikm, info, lengthBytes = KEY_BYTES, salt = new Uint8Array(0)) {
+  const infoBytes = info instanceof Uint8Array ? info : utf8Encode(info);
+  const keyMaterial = await subtle().importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+  const bits = await subtle().deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt, info: infoBytes },
+    keyMaterial,
+    lengthBytes * 8
+  );
+  return new Uint8Array(bits);
+}
+
+/**
+ * Import raw bytes as an AES-GCM key.
+ * @param {Uint8Array} raw
+ * @param {KeyUsage[]} usages
+ */
+async function importAesKey(raw, usages) {
+  if (raw.length !== KEY_BYTES) {
+    throw new Error(`AES key must be ${KEY_BYTES} bytes, got ${raw.length}`);
+  }
+  return subtle().importKey('raw', raw, { name: 'AES-GCM' }, false, usages);
+}
+
+/**
+ * AES-256-GCM encrypt with a fresh random IV.
+ *
+ * GCM is authenticated, so there is no separate MAC key to manage and a
+ * tampered ciphertext fails to decrypt rather than returning garbage. The IV is
+ * generated here and never accepted from a caller — reusing an IV under the same
+ * key destroys the security of the mode entirely.
+ *
+ * @param {Uint8Array} key 32 bytes
+ * @param {Uint8Array} plaintext
+ * @param {Uint8Array} [aad] additional authenticated data — bound to the
+ *   ciphertext but not encrypted. Use it to tie a ciphertext to its row, so a
+ *   server cannot move ciphertexts between records undetected.
+ * @returns {Promise<{ iv: Uint8Array, ciphertext: Uint8Array }>}
+ */
+export async function aesGcmEncrypt(key, plaintext, aad) {
+  const cryptoKey = await importAesKey(key, ['encrypt']);
+  const iv = randomBytes(IV_BYTES);
+  const params = { name: 'AES-GCM', iv };
+  if (aad) params.additionalData = aad;
+  const ciphertext = await subtle().encrypt(params, cryptoKey, plaintext);
+  return { iv, ciphertext: new Uint8Array(ciphertext) };
+}
+
+/**
+ * AES-256-GCM decrypt. Throws when the key is wrong, the ciphertext was
+ * altered, or the AAD does not match what was bound at encryption time.
+ * @param {Uint8Array} key
+ * @param {Uint8Array} iv
+ * @param {Uint8Array} ciphertext
+ * @param {Uint8Array} [aad]
+ * @returns {Promise<Uint8Array>}
+ */
+export async function aesGcmDecrypt(key, iv, ciphertext, aad) {
+  const cryptoKey = await importAesKey(key, ['decrypt']);
+  const params = { name: 'AES-GCM', iv };
+  if (aad) params.additionalData = aad;
+  const plaintext = await subtle().decrypt(params, cryptoKey, ciphertext);
+  return new Uint8Array(plaintext);
+}
diff --git a/packages/vault/src/vault-key.js b/packages/vault/src/vault-key.js
new file mode 100644
index 0000000..7544dd6
--- /dev/null
+++ b/packages/vault/src/vault-key.js
@@ -0,0 +1,236 @@
+/**
+ * Vault key lifecycle: creation, unlock, recovery and master-password change.
+ *
+ * The whole design turns on one indirection. Items are encrypted with a random
+ * **user key**, and the master password only ever encrypts that one key. So
+ * changing the master password re-encrypts 32 bytes instead of every item, and
+ * a second wrapped copy under a recovery key gives a way back in without the
+ * server learning anything.
+ */
+
+import {
+  randomBytes,
+  aesGcmEncrypt,
+  aesGcmDecrypt,
+  toBase64,
+  fromBase64,
+  toHex,
+  fromHex,
+  hkdf,
+  KEY_BYTES,
+} from './primitives.js';
+import {
+  DEFAULT_KDF_PARAMS,
+  INFO_RECOVERY,
+  assertUsableKdfParams,
+  deriveAll,
+  deriveWrapKey,
+} from './kdf.js';
+
+/** Salt length for the master-password KDF. */
+export const SALT_BYTES = 32;
+/** Recovery key entropy. 160 bits, short enough to write down. */
+export const RECOVERY_KEY_BYTES = 20;
+
+/**
+ * @typedef {Object} VaultMeta
+ * @property {string} kdf
+ * @property {number} iterations
+ * @property {string} salt                  base64
+ * @property {string} protectedUserKey      base64 ciphertext
+ * @property {string} protectedUserKeyIv    base64
+ * @property {string} authHash              base64, sent to the server
+ * @property {string} [recoveryKeyBlob]     base64 ciphertext
+ * @property {string} [recoveryKeyIv]       base64
+ */
+
+/**
+ * Render a recovery key for a human to write down: uppercase hex in groups of
+ * five, which survives being read aloud and retyped.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function formatRecoveryKey(bytes) {
+  return (toHex(bytes).toUpperCase().match(/.{1,5}/g) || []).join('-');
+}
+
+/**
+ * Accept a recovery key back in any casing, with or without separators.
+ * @param {string} formatted
+ * @returns {Uint8Array}
+ */
+export function parseRecoveryKey(formatted) {
+  const bytes = fromHex(String(formatted || ''));
+  if (bytes.length !== RECOVERY_KEY_BYTES) {
+    throw new Error('That does not look like a recovery key');
+  }
+  return bytes;
+}
+
+/**
+ * Wrap the user key under a key-encrypting key.
+ * @param {Uint8Array} kek
+ * @param {Uint8Array} userKey
+ * @returns {Promise<{ blob: string, iv: string }>}
+ */
+async function wrapUserKey(kek, userKey) {
+  const { iv, ciphertext } = await aesGcmEncrypt(kek, userKey);
+  return { blob: toBase64(ciphertext), iv: toBase64(iv) };
+}
+
+/**
+ * Unwrap the user key. Throws when the password (or recovery key) is wrong —
+ * GCM authentication fails rather than yielding a wrong-but-plausible key.
+ * @param {Uint8Array} kek
+ * @param {string} blob base64
+ * @param {string} iv base64
+ * @returns {Promise<Uint8Array>}
+ */
+async function unwrapUserKey(kek, blob, iv) {
+  try {
+    return await aesGcmDecrypt(kek, fromBase64(iv), fromBase64(blob));
+  } catch {
+    throw new Error('Incorrect password');
+  }
+}
+
+/**
+ * Create a brand-new vault.
+ *
+ * Everything returned in `meta` is safe to hand to the server. `userKey` and
+ * `recoveryKey` are not — the caller holds the first in memory for the session
+ * and shows the second to the user exactly once.
+ *
+ * @param {string} password
+ * @param {{ params?: {kdf: string, iterations: number} }} [options]
+ * @returns {Promise<{ meta: VaultMeta, userKey: Uint8Array, recoveryKey: string }>}
+ */
+export async function createVault(password, { params = DEFAULT_KDF_PARAMS } = {}) {
+  assertUsableKdfParams(params);
+
+  const salt = randomBytes(SALT_BYTES);
+  const { wrapKey, authHash } = await deriveAll(password, salt, params);
+
+  // The one key that actually encrypts items. Random, never derived from the
+  // password, so the password can change without touching a single item.
+  const userKey = randomBytes(KEY_BYTES);
+
+  const recoveryBytes = randomBytes(RECOVERY_KEY_BYTES);
+  const recoveryKek = await hkdf(recoveryBytes, INFO_RECOVERY, KEY_BYTES);
+
+  const [wrapped, recoveryWrapped] = await Promise.all([
+    wrapUserKey(wrapKey, userKey),
+    wrapUserKey(recoveryKek, userKey),
+  ]);
+
+  return {
+    meta: {
+      kdf: params.kdf,
+      iterations: params.iterations,
+      salt: toBase64(salt),
+      protectedUserKey: wrapped.blob,
+      protectedUserKeyIv: wrapped.iv,
+      authHash,
+      recoveryKeyBlob: recoveryWrapped.blob,
+      recoveryKeyIv: recoveryWrapped.iv,
+    },
+    userKey,
+    recoveryKey: formatRecoveryKey(recoveryBytes),
+  };
+}
+
+/**
+ * Unlock an existing vault.
+ * @param {string} password
+ * @param {VaultMeta} meta as returned by the server
+ * @returns {Promise<{ userKey: Uint8Array, authHash: string }>}
+ */
+export async function unlockVault(password, meta) {
+  // Validates the server-supplied KDF parameters before doing any work with
+  // them — see MIN_PBKDF2_ITERATIONS for why that matters.
+  const params = assertUsableKdfParams(meta);
+  const salt = fromBase64(meta.salt);
+  const { wrapKey, authHash } = await deriveAll(password, salt, params);
+  const userKey = await unwrapUserKey(wrapKey, meta.protectedUserKey, meta.protectedUserKeyIv);
+  return { userKey, authHash };
+}
+
+/**
+ * Unlock with the recovery key, for a forgotten master password.
+ * @param {string} recoveryKey as shown to the user at setup
+ * @param {VaultMeta} meta
+ * @returns {Promise<{ userKey: Uint8Array }>}
+ */
+export async function unlockWithRecoveryKey(recoveryKey, meta) {
+  if (!meta?.recoveryKeyBlob || !meta?.recoveryKeyIv) {
+    throw new Error('This vault has no recovery key');
+  }
+  const recoveryBytes = parseRecoveryKey(recoveryKey);
+  const recoveryKek = await hkdf(recoveryBytes, INFO_RECOVERY, KEY_BYTES);
+  try {
+    const userKey = await aesGcmDecrypt(
+      recoveryKek,
+      fromBase64(meta.recoveryKeyIv),
+      fromBase64(meta.recoveryKeyBlob)
+    );
+    return { userKey };
+  } catch {
+    throw new Error('Incorrect recovery key');
+  }
+}
+
+/**
+ * Change the master password.
+ *
+ * Re-wraps the same user key under a key derived from the new password, so no
+ * item is touched and nothing needs re-uploading. A fresh salt is generated,
+ * and the KDF parameters are upgraded to current defaults on the way through —
+ * which is how a vault created under weaker parameters gets stronger.
+ *
+ * @param {Uint8Array} userKey the unlocked key, from unlockVault
+ * @param {string} newPassword
+ * @param {VaultMeta} meta the existing metadata (recovery blob is preserved)
+ * @param {{ params?: {kdf: string, iterations: number} }} [options]
+ * @returns {Promise<{ meta: VaultMeta }>}
+ */
+export async function rewrapUserKey(userKey, newPassword, meta, { params = DEFAULT_KDF_PARAMS } = {}) {
+  assertUsableKdfParams(params);
+  if (!(userKey instanceof Uint8Array) || userKey.length !== KEY_BYTES) {
+    throw new Error('A valid unlocked user key is required');
+  }
+
+  const salt = randomBytes(SALT_BYTES);
+  const { wrapKey, authHash } = await deriveAll(newPassword, salt, params);
+  const wrapped = await wrapUserKey(wrapKey, userKey);
+
+  return {
+    meta: {
+      ...meta,
+      kdf: params.kdf,
+      iterations: params.iterations,
+      salt: toBase64(salt),
+      protectedUserKey: wrapped.blob,
+      protectedUserKeyIv: wrapped.iv,
+      authHash,
+    },
+  };
+}
+
+/**
+ * Issue a new recovery key, invalidating the previous one.
+ * @param {Uint8Array} userKey
+ * @param {VaultMeta} meta
+ * @returns {Promise<{ meta: VaultMeta, recoveryKey: string }>}
+ */
+export async function resetRecoveryKey(userKey, meta) {
+  const recoveryBytes = randomBytes(RECOVERY_KEY_BYTES);
+  const recoveryKek = await hkdf(recoveryBytes, INFO_RECOVERY, KEY_BYTES);
+  const wrapped = await wrapUserKey(recoveryKek, userKey);
+  return {
+    meta: { ...meta, recoveryKeyBlob: wrapped.blob, recoveryKeyIv: wrapped.iv },
+    recoveryKey: formatRecoveryKey(recoveryBytes),
+  };
+}
+
+/** Re-export so callers need only this module for the wrap key. */
+export { deriveWrapKey };
diff --git a/packages/vault/vitest.config.js b/packages/vault/vitest.config.js
new file mode 100644
index 0000000..f9a165c
--- /dev/null
+++ b/packages/vault/vitest.config.js
@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['__tests__/**/*.test.js'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.js'],
+    },
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fb4e90d..0dc4755 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -236,6 +236,12 @@ importers:
         specifier: ^2.1.8
         version: 2.1.9(@types/node@22.19.3)(jsdom@27.3.0)
 
+  packages/vault:
+    devDependencies:
+      vitest:
+        specifier: ^2.1.8
+        version: 2.1.9(@types/node@22.19.3)(jsdom@27.3.0)
+
 packages:
 
   '@acemir/cssom@0.9.30':
@@ -6342,7 +6348,7 @@ snapshots:
       eslint: 9.39.2(jiti@1.21.7)
       eslint-import-resolver-node: 0.3.9
       eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7))
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@1.21.7))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.2(jiti@1.21.7))
       eslint-plugin-react: 7.37.5(eslint@9.39.2(jiti@1.21.7))
       eslint-plugin-react-hooks: 7.0.1(eslint@9.39.2(jiti@1.21.7))
@@ -6375,7 +6381,7 @@ snapshots:
       tinyglobby: 0.2.15
       unrs-resolver: 1.11.1
     optionalDependencies:
-      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@1.21.7))
+      eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7))
     transitivePeerDependencies:
       - supports-color
 
@@ -6390,7 +6396,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.2(jiti@1.21.7)):
+  eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.50.0(eslint@9.39.2(jiti@1.21.7))(typescript@5.9.3))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7)))(eslint@9.39.2(jiti@1.21.7)):
     dependencies:
       '@rtsao/scc': 1.1.0
       array-includes: 3.1.9
diff --git a/supabase/migrations/20260829120000_vault.sql b/supabase/migrations/20260829120000_vault.sql
new file mode 100644
index 0000000..a5edfdc
--- /dev/null
+++ b/supabase/migrations/20260829120000_vault.sql
@@ -0,0 +1,189 @@
+-- MarkSyncr Vault — end-to-end encrypted password manager
+--
+-- The server stores ciphertext and never holds a key that can open it. Every
+-- value in these tables was encrypted or derived on the client by
+-- @marksyncr/vault; nothing here can be decrypted with anything the database,
+-- its backups, or an operator with full access can see.
+--
+-- Two deliberate design points:
+--
+--  * Keys and ciphertext are base64 TEXT rather than BYTEA. The API speaks JSON
+--    over PostgREST, where bytea round-trips as an escaped hex string and
+--    invites encoding mistakes on exactly the values that must not be corrupted.
+--
+--  * vault_items is one row per item, unlike cloud_bookmarks which stores a
+--    single JSONB blob. Two devices editing two *different* passwords at the
+--    same moment must not cost anyone a credential, and with one blob the later
+--    write silently discards the earlier. Per-row `revision` makes that a
+--    detectable conflict instead.
+
+-- ============================================
+-- Vault metadata — one row per user
+-- ============================================
+CREATE TABLE IF NOT EXISTS public.vault_meta (
+    user_id UUID PRIMARY KEY REFERENCES public.users(id) ON DELETE CASCADE,
+
+    -- KDF parameters travel with the vault so they can be strengthened later
+    -- without invalidating anyone's data. The client refuses to derive below its
+    -- own floor, so a compromised server cannot downgrade these to something
+    -- cheap to attack.
+    kdf TEXT NOT NULL DEFAULT 'pbkdf2-sha256',
+    kdf_iterations INTEGER NOT NULL DEFAULT 600000,
+    kdf_memory_kib INTEGER,      -- reserved for argon2id
+    kdf_parallelism INTEGER,     -- reserved for argon2id
+    kdf_salt TEXT NOT NULL,      -- base64, per user
+
+    -- The user key, encrypted under a key derived from the master password.
+    protected_user_key TEXT NOT NULL,
+    protected_user_key_iv TEXT NOT NULL,
+
+    -- A second copy of the same user key under the recovery key, so a forgotten
+    -- master password is survivable without the server learning anything.
+    recovery_key_blob TEXT,
+    recovery_key_iv TEXT,
+
+    -- Server-side hash of the client's auth hash. The client derives its auth
+    -- value from a different HKDF label than the wrapping key, so this column is
+    -- useless for decryption even in full.
+    auth_hash TEXT NOT NULL,
+
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT vault_meta_kdf_supported CHECK (kdf IN ('pbkdf2-sha256', 'argon2id')),
+    -- Mirrors MIN_PBKDF2_ITERATIONS in packages/vault/src/kdf.js. Defence in
+    -- depth: the client refuses weak parameters, and so does the database.
+    CONSTRAINT vault_meta_kdf_iterations_sane CHECK (kdf_iterations >= 100000)
+);
+
+-- ============================================
+-- Vault items — one row per login / card / identity / note
+-- ============================================
+CREATE TABLE IF NOT EXISTS public.vault_items (
+    -- Generated on the client, because the id is bound into the ciphertext as
+    -- additional authenticated data. A ciphertext moved to another row fails to
+    -- decrypt rather than silently showing the wrong credential.
+    id UUID PRIMARY KEY,
+    user_id UUID NOT NULL REFERENCES public.users(id) ON DELETE CASCADE,
+
+    -- 1 login, 2 card, 3 identity, 4 note. Plaintext on purpose so the server
+    -- can filter and count without decrypting; this is the metadata the design
+    -- accepts leaking.
+    type SMALLINT NOT NULL,
+
+    ciphertext TEXT NOT NULL,
+    iv TEXT NOT NULL,
+
+    -- Optimistic concurrency. A client sends the revision it read; the API
+    -- rejects the write if it has moved on.
+    revision BIGINT NOT NULL DEFAULT 1,
+
+    -- Trash bin. deleted_at set means hidden; purge_after is when it stops
+    -- being recoverable.
+    deleted_at TIMESTAMPTZ,
+    purge_after TIMESTAMPTZ,
+
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT vault_items_type_known CHECK (type BETWEEN 1 AND 4),
+    CONSTRAINT vault_items_trash_consistent CHECK (
+        (deleted_at IS NULL AND purge_after IS NULL)
+        OR (deleted_at IS NOT NULL AND purge_after IS NOT NULL)
+    )
+);
+
+CREATE INDEX IF NOT EXISTS idx_vault_items_user_updated
+    ON public.vault_items (user_id, updated_at DESC);
+
+-- The common read: everything not in the trash.
+CREATE INDEX IF NOT EXISTS idx_vault_items_user_active
+    ON public.vault_items (user_id)
+    WHERE deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_vault_items_purge
+    ON public.vault_items (purge_after)
+    WHERE purge_after IS NOT NULL;
+
+-- ============================================
+-- Row level security
+-- ============================================
+ALTER TABLE public.vault_meta ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.vault_items ENABLE ROW LEVEL SECURITY;
+
+-- (SELECT auth.uid()) rather than a bare auth.uid() so the planner evaluates it
+-- once per query instead of once per row — the same fix migration 013 applied
+-- to the existing tables.
+CREATE POLICY "Users can view own vault meta" ON public.vault_meta
+    FOR SELECT USING ((SELECT auth.uid()) = user_id);
+CREATE POLICY "Users can insert own vault meta" ON public.vault_meta
+    FOR INSERT WITH CHECK ((SELECT auth.uid()) = user_id);
+CREATE POLICY "Users can update own vault meta" ON public.vault_meta
+    FOR UPDATE USING ((SELECT auth.uid()) = user_id)
+    WITH CHECK ((SELECT auth.uid()) = user_id);
+CREATE POLICY "Users can delete own vault meta" ON public.vault_meta
+    FOR DELETE USING ((SELECT auth.uid()) = user_id);
+
+CREATE POLICY "Users can view own vault items" ON public.vault_items
+    FOR SELECT USING ((SELECT auth.uid()) = user_id);
+CREATE POLICY "Users can insert own vault items" ON public.vault_items
+    FOR INSERT WITH CHECK ((SELECT auth.uid()) = user_id);
+CREATE POLICY "Users can update own vault items" ON public.vault_items
+    FOR UPDATE USING ((SELECT auth.uid()) = user_id)
+    WITH CHECK ((SELECT auth.uid()) = user_id);
+CREATE POLICY "Users can delete own vault items" ON public.vault_items
+    FOR DELETE USING ((SELECT auth.uid()) = user_id);
+
+-- ============================================
+-- Triggers
+-- ============================================
+CREATE TRIGGER update_vault_meta_updated_at
+    BEFORE UPDATE ON public.vault_meta
+    FOR EACH ROW EXECUTE FUNCTION public.update_updated_at();
+
+-- Bumps updated_at AND revision on every write, so a client cannot forget to
+-- move the revision and quietly defeat conflict detection.
+-- SET search_path is required here; migration 012 fixed exactly this advisory
+-- across the existing functions.
+CREATE OR REPLACE FUNCTION public.bump_vault_item_revision()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+SET search_path = public
+AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    NEW.revision = OLD.revision + 1;
+    RETURN NEW;
+END;
+$$;
+
+CREATE TRIGGER bump_vault_items_revision
+    BEFORE UPDATE ON public.vault_items
+    FOR EACH ROW EXECUTE FUNCTION public.bump_vault_item_revision();
+
+-- ============================================
+-- Trash purge
+-- ============================================
+-- Hard-deletes items whose recovery window has passed. Safe to call from the
+-- API on a read (it is indexed and usually a no-op), or from pg_cron where that
+-- extension is available.
+CREATE OR REPLACE FUNCTION public.purge_expired_vault_items()
+RETURNS INTEGER
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+    purged INTEGER;
+BEGIN
+    DELETE FROM public.vault_items
+    WHERE purge_after IS NOT NULL AND purge_after < NOW();
+    GET DIAGNOSTICS purged = ROW_COUNT;
+    RETURN purged;
+END;
+$$;
+
+COMMENT ON TABLE public.vault_meta IS
+    'Per-user vault key material. Every value is encrypted or derived client-side; the server cannot decrypt any of it.';
+COMMENT ON TABLE public.vault_items IS
+    'Encrypted vault items. Only id, type and timestamps are plaintext — see the migration header for the metadata this deliberately leaks.';