cursedbelt-server 1.0.0

package/src/server/auth/sessionStore.ts

@@ -0,0 +1,261 @@
+import type { PlumbingDb } from '../db/kysely';
+import type { AuthSessionRow } from '../db/plumbingTypes';
+import type { CreateSessionInput, Session, SessionStore } from './types';
+
+/**
+ * Kysely-backed, revocable, restart-surviving session store (task 26).
+ *
+ * The in-memory map is the hot-path source of truth for token validity — the auth
+ * middleware reads it synchronously, no per-request DB round-trip. The
+ * `auth_sessions` table exists only so the map can be rebuilt after a restart
+ * ({@link SessionStore.rehydrate}); DB writes for sliding `touch`es are throttled
+ * (memory is always current). Single-server deployment, so there is no
+ * cross-instance coherence to manage.
+ */
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+export interface SessionStoreOptions {
+  /** Sliding refresh window — how long after the last activity a session stays
+   * valid. Default 7 days. */
+  refreshWindowMs?: number;
+  /** Retention before a stale (lapsed) row is pruned from memory + DB. Default 30
+   * days. Must be ≥ refreshWindowMs to keep recently-expired rows for the audit view. */
+  retentionMs?: number;
+  /** Throttle window for sliding-`touch` DB writes. Memory is always current; the
+   * row is flushed at most this often (unless a token re-issue forces it). Default 60s. */
+  flushIntervalMs?: number;
+  /** Start a background prune timer. Default false — wire pruning through the job
+   * runner (task 29), or call {@link SessionStore.prune} yourself. */
+  autoPrune?: boolean;
+  /** Auto-prune cadence when {@link autoPrune} is on. Default 1 hour. */
+  pruneIntervalMs?: number;
+}
+
+const rowToSession = (r: AuthSessionRow): Session => ({
+  sessionId: r.session_id,
+  userId: r.user_id,
+  getOnly: r.get_only === 1,
+  createdAt: r.created_at,
+  lastSeenAt: r.last_seen_at,
+  refreshExpiresAt: r.refresh_expires_at,
+  accessExpiresAt: r.access_expires_at,
+  disabled: r.disabled === 1,
+  disabledAt: r.disabled_at,
+  disabledBy: r.disabled_by,
+  userAgent: r.user_agent,
+  ip: r.ip,
+});
+
+export function createSessionStore(ky: PlumbingDb, opts: SessionStoreOptions = {}): SessionStore {
+  const refreshWindowMs = opts.refreshWindowMs ?? 7 * DAY_MS;
+  const retentionMs = opts.retentionMs ?? 30 * DAY_MS;
+  const flushIntervalMs = opts.flushIntervalMs ?? 60_000;
+  const pruneIntervalMs = opts.pruneIntervalMs ?? HOUR_MS;
+
+  const map = new Map<string, Session>();
+  const lastFlushAt = new Map<string, number>();
+  let pruneTimer: ReturnType<typeof setInterval> | undefined;
+
+  const isFresh = (s: Session | undefined, now = Date.now()): s is Session =>
+    !!s && !s.disabled && Date.parse(s.refreshExpiresAt) >= now;
+
+  const store: SessionStore = {
+    async rehydrate() {
+      // Drop ancient rows first so the map starts trim, then load only currently-valid
+      // sessions (disabled/expired rows stay in the DB for the audit view).
+      await store.prune();
+      const rows = await ky.selectFrom('auth_sessions').selectAll().execute();
+      const now = Date.now();
+      map.clear();
+      lastFlushAt.clear();
+      for (const r of rows) {
+        const s = rowToSession(r);
+        if (isFresh(s, now)) {
+          map.set(s.sessionId, s);
+          lastFlushAt.set(s.sessionId, now);
+        }
+      }
+    },
+
+    async create(input: CreateSessionInput) {
+      const now = Date.now();
+      const nowIso = new Date(now).toISOString();
+      const session: Session = {
+        sessionId: input.sessionId,
+        userId: input.userId,
+        getOnly: input.getOnly ?? false,
+        createdAt: nowIso,
+        lastSeenAt: nowIso,
+        refreshExpiresAt: input.refreshExpiresAt ?? new Date(now + refreshWindowMs).toISOString(),
+        accessExpiresAt: input.accessExpiresAt ?? null,
+        disabled: false,
+        disabledAt: null,
+        disabledBy: null,
+        userAgent: input.userAgent ?? null,
+        ip: input.ip ?? null,
+      };
+      map.set(session.sessionId, session);
+      lastFlushAt.set(session.sessionId, now);
+      await ky
+        .insertInto('auth_sessions')
+        .values({
+          session_id: session.sessionId,
+          user_id: session.userId,
+          get_only: session.getOnly ? 1 : 0,
+          created_at: session.createdAt,
+          last_seen_at: session.lastSeenAt,
+          refresh_expires_at: session.refreshExpiresAt,
+          access_expires_at: session.accessExpiresAt,
+          disabled: 0,
+          disabled_at: null,
+          disabled_by: null,
+          user_agent: session.userAgent,
+          ip: session.ip,
+        })
+        .execute();
+      return session;
+    },
+
+    get(sessionId) {
+      return map.get(sessionId);
+    },
+
+    isValid(session): session is Session {
+      return isFresh(session);
+    },
+
+    async touch(sessionId, opts2) {
+      const s = map.get(sessionId);
+      if (!s) return;
+      const now = Date.now();
+      s.lastSeenAt = new Date(now).toISOString();
+      s.refreshExpiresAt = new Date(now + refreshWindowMs).toISOString();
+      const reissued = opts2?.accessExpiresAt !== undefined;
+      if (reissued) s.accessExpiresAt = opts2?.accessExpiresAt ?? null;
+
+      const last = lastFlushAt.get(sessionId) ?? 0;
+      if (reissued || now - last > flushIntervalMs) {
+        await ky
+          .updateTable('auth_sessions')
+          .set({
+            last_seen_at: s.lastSeenAt,
+            refresh_expires_at: s.refreshExpiresAt,
+            access_expires_at: s.accessExpiresAt,
+          })
+          .where('session_id', '=', sessionId)
+          .execute();
+        lastFlushAt.set(sessionId, now);
+      }
+    },
+
+    async disable(sessionId, disabledBy = null) {
+      const s = map.get(sessionId);
+      const nowIso = new Date().toISOString();
+      if (s) {
+        s.disabled = true;
+        s.disabledAt = nowIso;
+        s.disabledBy = disabledBy;
+      }
+      const res = await ky
+        .updateTable('auth_sessions')
+        .set({ disabled: 1, disabled_at: nowIso, disabled_by: disabledBy })
+        .where('session_id', '=', sessionId)
+        .where('disabled', '=', 0)
+        .executeTakeFirst();
+      return s !== undefined || Number(res?.numUpdatedRows ?? 0) > 0;
+    },
+
+    async disableAllForUser(userId, disabledBy = null) {
+      const nowIso = new Date().toISOString();
+      const affected: string[] = [];
+      for (const s of map.values()) {
+        if (s.userId === userId && !s.disabled) {
+          s.disabled = true;
+          s.disabledAt = nowIso;
+          s.disabledBy = disabledBy;
+          affected.push(s.sessionId);
+        }
+      }
+      await ky
+        .updateTable('auth_sessions')
+        .set({ disabled: 1, disabled_at: nowIso, disabled_by: disabledBy })
+        .where('user_id', '=', userId)
+        .where('disabled', '=', 0)
+        .execute();
+      return affected;
+    },
+
+    async remove(sessionId) {
+      map.delete(sessionId);
+      lastFlushAt.delete(sessionId);
+      await ky.deleteFrom('auth_sessions').where('session_id', '=', sessionId).execute();
+    },
+
+    async deleteByUser(userId) {
+      for (const [id, s] of map) {
+        if (s.userId === userId) {
+          map.delete(id);
+          lastFlushAt.delete(id);
+        }
+      }
+      await ky.deleteFrom('auth_sessions').where('user_id', '=', userId).execute();
+    },
+
+    async listByUser(userId) {
+      const rows = await ky
+        .selectFrom('auth_sessions')
+        .selectAll()
+        .where('user_id', '=', userId)
+        .orderBy('created_at', 'desc')
+        .execute();
+      return rows.map(rowToSession);
+    },
+
+    listAll() {
+      return Array.from(map.values());
+    },
+
+    getLastSeenForUser(userId) {
+      let latest: string | null = null;
+      for (const s of map.values()) {
+        if (s.userId !== userId || s.disabled) continue;
+        if (!latest || s.lastSeenAt > latest) latest = s.lastSeenAt;
+      }
+      return latest;
+    },
+
+    async prune() {
+      const cutoff = Date.now() - retentionMs;
+      const cutoffIso = new Date(cutoff).toISOString();
+      let removed = 0;
+      for (const [id, s] of map) {
+        if (Date.parse(s.lastSeenAt) < cutoff) {
+          map.delete(id);
+          lastFlushAt.delete(id);
+          removed++;
+        }
+      }
+      await ky.deleteFrom('auth_sessions').where('last_seen_at', '<', cutoffIso).execute();
+      return removed;
+    },
+
+    stop() {
+      if (pruneTimer) {
+        clearInterval(pruneTimer);
+        pruneTimer = undefined;
+      }
+    },
+  };
+
+  if (opts.autoPrune) {
+    pruneTimer = setInterval(() => {
+      void store.prune();
+    }, pruneIntervalMs);
+    // Never keep the process alive for a prune tick.
+    pruneTimer.unref?.();
+  }
+
+  return store;
+}

package/src/server/auth/totp.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test';
+import { generateSync } from 'otplib';
+import {
+  generateRecoveryCodes,
+  generateTotpSecret,
+  getTotpUri,
+  verifyRecoveryCode,
+  verifyTotpCode,
+} from './totp';
+
+describe('TOTP', () => {
+  test('generates a base32 secret', () => {
+    const secret = generateTotpSecret();
+    expect(secret).toMatch(/^[A-Z2-7]+$/);
+    expect(secret.length).toBeGreaterThanOrEqual(16);
+  });
+
+  test('builds an otpauth:// URI with issuer + label + secret', () => {
+    const secret = generateTotpSecret();
+    const uri = getTotpUri('user@example.com', secret, 'CursedAlchemy');
+    expect(uri.startsWith('otpauth://totp/')).toBe(true);
+    expect(uri).toContain('issuer=CursedAlchemy');
+    expect(uri).toContain(`secret=${secret}`);
+  });
+
+  test('verifies the current code, rejects a wrong one', () => {
+    const secret = generateTotpSecret();
+    const code = generateSync({ secret });
+    expect(verifyTotpCode(code, secret)).toBe(true);
+    expect(verifyTotpCode('000000', secret)).toBe(false);
+  });
+
+  test('tolerates whitespace and rejects non-6-digit input', () => {
+    const secret = generateTotpSecret();
+    const code = generateSync({ secret });
+    expect(verifyTotpCode(` ${code} `, secret)).toBe(true);
+    expect(verifyTotpCode('12345', secret)).toBe(false);
+    expect(verifyTotpCode('abcdef', secret)).toBe(false);
+    expect(verifyTotpCode('', secret)).toBe(false);
+  });
+
+  test('accepts a code from the previous 30s step (±1 drift)', () => {
+    const secret = generateTotpSecret();
+    const prev = generateSync({ secret, epoch: Math.floor(Date.now() / 1000) - 30 });
+    expect(verifyTotpCode(prev, secret)).toBe(true);
+  });
+});
+
+describe('recovery codes', () => {
+  test('generates N readable codes + argon2id hashes; never stores plaintext', async () => {
+    const { plaintext, hashed } = await generateRecoveryCodes(8);
+    expect(plaintext).toHaveLength(8);
+    expect(hashed).toHaveLength(8);
+    for (const h of hashed) expect(h.startsWith('$argon2id$')).toBe(true);
+    // a hash must not be the plaintext
+    expect(hashed[0]).not.toContain(plaintext[0]);
+  });
+
+  test('verifyRecoveryCode returns the matching index, tolerant of formatting', async () => {
+    const { plaintext, hashed } = await generateRecoveryCodes(5);
+    const idx = await verifyRecoveryCode(plaintext[2].toLowerCase().replace('-', ''), hashed);
+    expect(idx).toBe(2);
+  });
+
+  test('returns -1 for an unknown code, and after a code is consumed', async () => {
+    const { plaintext, hashed } = await generateRecoveryCodes(3);
+    expect(await verifyRecoveryCode('ZZZZZ-ZZZZZ', hashed)).toBe(-1);
+    // consume index 1 (the caller splices it out) → it no longer matches
+    const remaining = hashed.filter((_, i) => i !== 1);
+    expect(await verifyRecoveryCode(plaintext[1], remaining)).toBe(-1);
+    expect(await verifyRecoveryCode(plaintext[0], remaining)).toBe(0);
+  });
+});

package/src/server/auth/totp.ts

@@ -0,0 +1,92 @@
+import { generateSecret, generateURI, verifySync } from 'otplib';
+
+/**
+ * TOTP (RFC 6238) on `otplib` — standard authenticator-app parameters (base32
+ * secret, SHA-1, 6 digits, 30s step). otplib's default plugins are pure-JS
+ * (`@noble/hashes` + `@scure/base`), so this runs natively on Bun with no native
+ * deps. Plus single-use recovery codes hashed with argon2id (never stored plain).
+ *
+ * The toolkit provides the crypto; enabling/disabling 2FA, persisting the secret +
+ * recovery hashes, and the login-flow ordering stay app-business (task 32).
+ */
+
+export const DEFAULT_TOTP_ISSUER = 'CursedAlchemy';
+
+// One 30s step of clock-skew tolerance on each side (±1 step). otplib v13 defaults
+// to ZERO tolerance, so we set it explicitly (period = 30s).
+const DRIFT_SECONDS = 30;
+
+/** A fresh random base32 TOTP secret (20 bytes / 160 bits — the standard). */
+export function generateTotpSecret(): string {
+  return generateSecret();
+}
+
+/** The `otpauth://` URI an authenticator app scans / imports (for QR rendering). */
+export function getTotpUri(account: string, secret: string, issuer = DEFAULT_TOTP_ISSUER): string {
+  return generateURI({ issuer, label: account, secret });
+}
+
+/**
+ * Verify a user-entered 6-digit code against a base32 secret, allowing ±1 step of
+ * drift. Tolerates surrounding whitespace; rejects anything that isn't six digits.
+ */
+export function verifyTotpCode(token: string, secret: string): boolean {
+  const clean = String(token).replace(/\s+/g, '');
+  if (!/^\d{6}$/.test(clean)) return false;
+  try {
+    return verifySync({ secret, token: clean, epochTolerance: DRIFT_SECONDS }).valid;
+  } catch {
+    return false;
+  }
+}
+
+// ── Recovery codes ──────────────────────────────────────────────────────────────
+
+// No easily-confused characters (no 0/O, 1/I/L) — readable + dictatable.
+const CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+
+/** Strip separators + uppercase, so display formatting never affects matching. */
+const normalizeCode = (code: string): string =>
+  String(code)
+    .replace(/[^a-zA-Z0-9]/g, '')
+    .toUpperCase();
+
+const randomCode = (): string => {
+  const bytes = crypto.getRandomValues(new Uint8Array(10));
+  let s = '';
+  for (const b of bytes) s += CODE_ALPHABET[b % CODE_ALPHABET.length];
+  return `${s.slice(0, 5)}-${s.slice(5)}`; // e.g. "A1B2C-D3E4F"
+};
+
+/**
+ * Generate `count` single-use recovery codes. Returns `plaintext` (shown to the user
+ * exactly once) and `hashed` (argon2id PHC strings — persist these as a JSON array,
+ * never the plaintext).
+ */
+export async function generateRecoveryCodes(
+  count = 10,
+): Promise<{ plaintext: string[]; hashed: string[] }> {
+  const plaintext = Array.from({ length: count }, randomCode);
+  const hashed = await Promise.all(
+    plaintext.map((code) => Bun.password.hash(normalizeCode(code), { algorithm: 'argon2id' })),
+  );
+  return { plaintext, hashed };
+}
+
+/**
+ * Verify a candidate recovery code against the stored argon2id hashes. Returns the
+ * index of the matching hash, or -1 if none match. The caller consumes it (splice
+ * that index out and persist the shortened array) so each code works exactly once.
+ */
+export async function verifyRecoveryCode(input: string, hashed: string[]): Promise<number> {
+  const candidate = normalizeCode(input);
+  if (!candidate) return -1;
+  for (let i = 0; i < hashed.length; i++) {
+    try {
+      if (await Bun.password.verify(candidate, hashed[i])) return i;
+    } catch {
+      // ignore a malformed stored hash — treat as a non-match
+    }
+  }
+  return -1;
+}

package/src/server/auth/types.ts

@@ -0,0 +1,146 @@
+import type { JWTPayload } from 'jose';
+import type { CursedbeltVariables } from '../context';
+
+/**
+ * Shared auth types for the cursedbelt server auth toolkit.
+ *
+ * cursedbelt owns the *mechanism* (sign/verify, session validity, the getOnly
+ * gate, CSRF, throttling, TOTP, vault crypto). The *model* — which roles may do
+ * what, the `/f`-vs-`/login` policy, what a "session" means to the product — stays
+ * in the consuming app. The toolkit carries `roles`/`getOnly`/`purpose` opaquely
+ * and never interprets them beyond the documented gates.
+ */
+
+/** Token purposes the apps mint. `access` is the login session; the rest are
+ * short-lived single-feature unlock/state tokens (held in page memory, never a
+ * cookie). cursedbelt does not enforce these — {@link AppJwtPayload.purpose} is an
+ * opaque string the app sets and checks (via `verifyPurposeToken`). */
+export type TokenPurpose =
+  | 'access'
+  | 'refresh'
+  | 'vault-unlock'
+  | 'pm-unlock'
+  | 'files-unlock'
+  | 'yt-oauth';
+
+/**
+ * The decoded JWT payload shape the apps use. `userId`/`sessionId` tie a token to
+ * its user + its row in the session store (the kill switch); `roles` + `getOnly`
+ * ride along for the auth middleware to surface on `c.get('user')`.
+ */
+export interface AppJwtPayload extends JWTPayload {
+  userId: string;
+  sessionId: string;
+  roles: string[];
+  /** GET-only (`/f`) session marker. Absent on tokens minted before the claim
+   * existed → treated as `false` (see {@link AuthUser.getOnly}). */
+  getOnly?: boolean;
+  /** See {@link TokenPurpose}. Absent ⇒ a plain access token. */
+  purpose?: TokenPurpose | (string & {});
+}
+
+/**
+ * The authenticated principal the auth middleware sets on `c.get('user')`. This is
+ * the *normalized* view (getOnly defaulted), distinct from the raw {@link AppJwtPayload}.
+ */
+export interface AuthUser {
+  id: string;
+  roles: string[];
+  /** Normalized: a missing `getOnly` claim becomes `false` here. */
+  getOnly: boolean;
+  sessionId: string;
+}
+
+/** Hono `Variables` the auth middleware contributes. Composed with the base
+ * {@link CursedbeltVariables} into {@link AuthEnv}. */
+export interface AuthVariables {
+  /** Set by `createAuthMiddleware` once the token + session are validated. */
+  user: AuthUser;
+}
+
+/** The Hono env an app gets once it mounts the cursedbelt auth middleware: the
+ * base plumbing variables plus the authenticated `user`. `user` is typed required
+ * because the gate runs before any handler that reads it; mount auth before the
+ * routes that depend on it. */
+export interface AuthEnv {
+  Variables: CursedbeltVariables & AuthVariables;
+}
+
+/** A persisted login session — the in-memory + DB-backed record the auth middleware
+ * checks on every request (revocation + sliding-refresh expiry). */
+export interface Session {
+  sessionId: string;
+  userId: string;
+  /** GET-only (`/f`) session. Copied onto the access token's `getOnly` claim. */
+  getOnly: boolean;
+  createdAt: string;
+  lastSeenAt: string;
+  /** Sliding deadline: a session is valid while now < refreshExpiresAt. */
+  refreshExpiresAt: string;
+  /** When the *current* access token expires (informational; the cookie/JWT is the
+   * real gate). Null until first issued. */
+  accessExpiresAt: string | null;
+  disabled: boolean;
+  disabledAt: string | null;
+  disabledBy: string | null;
+  userAgent: string | null;
+  ip: string | null;
+}
+
+/** Inputs to mint a session. The store computes `createdAt`/`lastSeenAt` and (unless
+ * overridden) `refreshExpiresAt` from its configured window — callers never hand-roll
+ * timestamps. */
+export interface CreateSessionInput {
+  sessionId: string;
+  userId: string;
+  getOnly?: boolean;
+  accessExpiresAt?: string | null;
+  userAgent?: string | null;
+  ip?: string | null;
+  /** Override the computed `now + refreshWindowMs` deadline. */
+  refreshExpiresAt?: string;
+}
+
+/**
+ * Revocable, restart-surviving session store. The in-memory map is the hot-path
+ * source of truth for token validity (no per-request DB read); the `auth_sessions`
+ * table exists so the map can be rebuilt after a restart ({@link SessionStore.rehydrate}).
+ * Single-server deployment — no cross-instance coherence to manage.
+ */
+export interface SessionStore {
+  /** Load the table into memory on boot (prunes expired/old rows first). */
+  rehydrate(): Promise<void>;
+  /** Persist + cache a new session. */
+  create(input: CreateSessionInput): Promise<Session>;
+  /** Sync hot-path read from memory. Returns the LIVE cached object (not a copy) —
+   * treat it read-only; mutate only through the store's methods. */
+  get(sessionId: string): Session | undefined;
+  /** Is this session usable right now (present, not disabled, inside its window)? */
+  isValid(session: Session | undefined): session is Session;
+  /** Slide the refresh deadline forward on activity (and optionally record a freshly
+   * issued access-token expiry). DB write is throttled unless `accessExpiresAt` is
+   * passed (a re-issue must persist immediately so a restart reflects it). */
+  touch(sessionId: string, opts?: { accessExpiresAt?: string | null }): Promise<void>;
+  /** Revoke one session (keeps the audit row). Returns false if unknown. */
+  disable(sessionId: string, disabledBy?: string | null): Promise<boolean>;
+  /** Revoke every active session for a user; returns the affected ids (e.g. to drop
+   * matching live websockets). */
+  disableAllForUser(userId: string, disabledBy?: string | null): Promise<string[]>;
+  /** Forget a single session entirely (logout — drops the audit row too). */
+  remove(sessionId: string): Promise<void>;
+  /** Hard-delete every session for a user (memory + DB). */
+  deleteByUser(userId: string): Promise<void>;
+  /** All sessions for a user (incl. disabled audit rows), newest first — for an
+   * account/admin "your devices" view. */
+  listByUser(userId: string): Promise<Session[]>;
+  /** All cached sessions (sync; admin live list). */
+  listAll(): Session[];
+  /** Most-recent activity across a user's active sessions, or null — a cheap presence
+   * signal. */
+  getLastSeenForUser(userId: string): string | null;
+  /** Drop sessions whose last activity predates the retention window (memory + DB).
+   * Returns the count removed. */
+  prune(): Promise<number>;
+  /** Stop the optional auto-prune timer (no-op if none was started). */
+  stop(): void;
+}

package/src/server/auth/vault.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test';
+import { decryptVaultItem, deriveVaultKey, encryptVaultItem } from './vault';
+
+const SECRET = 'server-secret-used-for-vault-key-derivation';
+
+describe('vault item crypto (AES-256-GCM + HKDF)', () => {
+  test('encrypt → decrypt roundtrips the plaintext', async () => {
+    const key = await deriveVaultKey(SECRET, 'user-1');
+    const plaintext = 'sꜱh key: hunter2 🔐 — multi-byte ✓';
+    const envelope = await encryptVaultItem(key, plaintext);
+    expect(await decryptVaultItem(key, envelope)).toBe(plaintext);
+  });
+
+  test('each encryption uses a fresh IV (ciphertext differs)', async () => {
+    const key = await deriveVaultKey(SECRET, 'user-1');
+    const a = await encryptVaultItem(key, 'same');
+    const b = await encryptVaultItem(key, 'same');
+    expect(a).not.toBe(b);
+    expect(await decryptVaultItem(key, a)).toBe('same');
+    expect(await decryptVaultItem(key, b)).toBe('same');
+  });
+
+  test('the envelope starts with the version byte (1)', async () => {
+    const key = await deriveVaultKey(SECRET, 'user-1');
+    const envelope = await encryptVaultItem(key, 'x');
+    expect(new Uint8Array(Buffer.from(envelope, 'base64'))[0]).toBe(1);
+  });
+
+  test('a different user derives a different key — cross-user decrypt fails', async () => {
+    const k1 = await deriveVaultKey(SECRET, 'user-1');
+    const k2 = await deriveVaultKey(SECRET, 'user-2');
+    const envelope = await encryptVaultItem(k1, 'secret');
+    await expect(decryptVaultItem(k2, envelope)).rejects.toThrow();
+  });
+
+  test('a tampered envelope fails the GCM auth check', async () => {
+    const key = await deriveVaultKey(SECRET, 'user-1');
+    const bytes = new Uint8Array(Buffer.from(await encryptVaultItem(key, 'secret'), 'base64'));
+    bytes[bytes.length - 1] ^= 0xff; // flip a ciphertext bit
+    await expect(decryptVaultItem(key, Buffer.from(bytes).toString('base64'))).rejects.toThrow();
+  });
+
+  test('rejects an unknown version byte', async () => {
+    const key = await deriveVaultKey(SECRET, 'user-1');
+    const bytes = new Uint8Array(Buffer.from(await encryptVaultItem(key, 'secret'), 'base64'));
+    bytes[0] = 2;
+    await expect(decryptVaultItem(key, Buffer.from(bytes).toString('base64'))).rejects.toThrow(
+      /version/,
+    );
+  });
+});