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.';