password_manager/AGENTS.md

# Password Vault — Agent Context

## Project Overview

An offline-first, single-file password manager built with **Svelte 5** (runes-based reactivity). All data is encrypted in-browser with AES-256-GCM and stored in IndexedDB. The production build is a single `dist/index.html` with zero network dependencies — it works from `file://`, USB, or any static server.

## Architecture

```
src/
├── App.svelte                  # Root component — routes between LockScreen, MainLayout
├── main.js                     # Entry point
├── components/
│   ├── LockScreen.svelte       # Master password setup + unlock UI
│   ├── MainLayout.svelte       # Shell: sidebar + content area
│   ├── Sidebar.svelte          # Group list + search bar
│   ├── EntryList.svelte        # Credential entries grid
│   ├── EntryForm.svelte        # Create/edit credential form
│   ├── EntryDetail.svelte      # View single entry (copy password/username)
│   ├── ImportExport.svelte     # JSON import/export with merge/replace
│   └── SettingsDialog.svelte   # Auto-lock and tab-switch settings
├── lib/
│   ├── crypto/crypto.js        # Web Crypto API: PBKDF2 key derivation, AES-GCM encrypt/decrypt, password generator
│   ├── storage/db.js           # IndexedDB layer (idb wrapper): entries, groups, meta stores, exportSelected(groupIds)
│   ├── models/schema.js        # Data models: CredentialEntry, Group; validation; ID generation
│   ├── autofocus.js            # Svelte action for autofocus on mount
│   └── stores/
│       ├── app.svelte.js       # AppStore: $state(isUnlocked, encryptionKey, salt)
│       ├── security.svelte.js  # Auto-lock timer, visibility change, beforeunload cleanup
│       ├── search.svelte.js    # Reactive search state
│       └── settings.svelte.js  # Reactive settings (auto-lock minutes, tab-switch lock)
```

## Key Design Decisions

- **Svelte 5 runes** — Use `$state`, `$derived`, `$effect`. Props-based event passing (no Svelte events). Event handler attributes are all lower-case (e.g. oninput)
- **No external crypto libraries** — Uses the browser's native Web Crypto API exclusively.
- **Key never persisted** — Encryption key lives only in `$state` memory; cleared on lock, tab switch, or page close.
- **Single-file build** — `vite-plugin-singlefile` inlines all JS/CSS; post-build script inlines favicon.
- **IndexedDB via `idb`** — Three stores: `entries`, `groups`, `meta`. Only `encryptedPassword` is encrypted at rest; titles, usernames, URLs, and notes are plaintext for searchability.
- **PBKDF2 key derivation** — 600,000 iterations, SHA-256, 256-bit AES-GCM key.
- **`GROUP_COLORS` exported from schema.js** — Shared between `createGroup()` and `Sidebar.svelte`.

## Encryption Flow

```
Master Password → PBKDF2 (600k iters, 16-byte salt) → AES-256-GCM Key → encrypt/decrypt credentials
```

Password verification uses a test payload (random string encrypted at vault creation). On unlock, the entered password derives a key that must successfully decrypt the test payload.

## Scripts

| Command | Description |
|---|---|
| `npm run dev` | Vite dev server with HMR on `:5173` |
| `npm run build` | Production build → `dist/index.html` (single self-contained file) |
| `npm run preview` | Preview production build |
| `npm run test` | Vitest (watch mode) |
| `npm run test:run` | Vitest (single run) |

## Testing

- Framework: **Vitest** with **jsdom** environment
- Test setup: `tests/setup.js` (fake-indexeddb polyfill, Web Crypto API polyfill)
- Test files:
  - `tests/lib/crypto/crypto.test.js` — Password generation, key derivation, encrypt/decrypt, verify, test payload, base64 utils
  - `tests/lib/models/schema.test.js` — ID generation, entry/group CRUD, validation, trash group
  - `tests/lib/storage/db.test.js` — Vault meta, settings, groups CRUD, entries CRUD, search, trash, export/import
  - `tests/lib/stores/app.test.js` — AppStore state and lockVault
  - `tests/lib/stores/search.test.js` — SearchStore query, group filter, clear
  - `tests/lib/stores/settings.test.js` — SettingsStore defaults, load, save
  - `tests/lib/stores/security.test.js` — Auto-lock timer, visibility change, beforeunload, activity reset
- Run with `npm run test` or `npm run test:run`

## Security Notes

- Only `encryptedPassword` and `encryptedTotpSecret` are encrypted at rest; other fields (title, username, URL, notes) are plaintext in IndexedDB. Passwords and TOTP secrets are optional on an entry.
- `testPlaintext` for password verification is stored unencrypted in the `meta` store.
- Auto-lock triggers on tab visibility change and configurable inactivity timer (default 5 min).
- Clipboard auto-clears after 15 seconds.
- No browser fingerprinting or anti-keylogger protections.

## TOTP (2FA)

- `src/lib/crypto/totp.js`: native RFC 6238 TOTP via Web Crypto HMAC-SHA1 (no external lib). Exports `generateTotp(secret, {timestamp, period=30, digits=6})`, `base32Decode`, `extractSecret` (accepts bare base32 OR `otpauth://` URI), `totpRemainingSeconds`.
- Entries store an optional `encryptedTotpSecret` (AES-GCM, like passwords). EntryForm accepts a base32 secret or otpauth:// URI; EntryDetail shows a live, copyable 6-digit code with a 1s countdown + urgency color, cleaned up via `onDestroy`.
- Export/import re-key `encryptedTotpSecret` alongside passwords for sealed exports (and decrypt/re-encrypt on import), so TOTP survives migration between vaults.
- Note: `extractSecret` must strip hyphens from hyphen-grouped secrets (authenticator display style) as well as whitespace.

## Export / Import

- `exportSelected(groupIds, options)` — group IDs to export; `null`/`[]` = full export (include `''` for ungrouped). `options = { vaultKey, password = '', useExistingPassword = false }`. An explicit protection choice is required; every protected export AES-256-GCM-seals the whole payload (titles/usernames/notes included) into `{ format: 'encrypted-export', salt, data }`.
  - **New password** (`options.password`): re-keys every exported entry's password to a key derived from that password + a fresh random salt (embedded in the envelope), so import needs only this password — never the vault's.
  - **Reuse existing password** (`options.useExistingPassword`): seals with the vault's own key and keeps the vault's salt embedded, so import derives the key from the vault master password. No second password to create/remember.
  - **No option set**: falls back to a plaintext JSON export (entries keep source-vault-encrypted passwords) for backward compatibility; the UI never offers this.
- `importAll(data, mode, password, targetKey)` detects a sealed export (`data.format === 'encrypted-export'`): `password` is whichever password opens the envelope — a separate export password OR the source vault's master password (for reuse-existing). A wrong password rejects the import (never silently skips). The entry loop decrypts with the reproduced source key and re-encrypts under `targetKey`.
- `ImportExport.svelte` fetches groups/entries on modal open and shows a checkbox list for group selection with live entry count. The export dialog forces an explicit choice via two radio options: "Use a new password" (shows a short password field, validated non-empty) or "Reuse my vault password". The import dialog's single password field is generic (export password for sealed files, source vault master for plain/old files).

## Known Bug Fixes

- `base64ToUint8Array` was used in `db.js` `importAll()` but never imported — now imported from `crypto.js`.
- `handlePermanentDelete()` in `EntryDetail.svelte` called `moveToTrash()` + `emptyTrash()` (wiping ALL trash) — now uses `deleteEntry()` directly.