# SeedPGP Agent Brief (read first)

## What this repo is

SeedPGP: a client-side BIP39 mnemonic encryption web app.
Goal: add features without changing security assumptions or breaking GH Pages deploy.

## Non-negotiables

- Small diffs only: one feature slice per PR (1-5 files if possible).
- No big code dumps; propose plan first, then implement.
- Never persist secrets (mnemonic, passphrases, private keys) to localStorage/sessionStorage.
- Prefer “explain what you found in the repo” over guessing.

## How to run

- Install deps: `bun install`
- Dev: `bun run dev`
- Build: `bun run build`
- Tests/lint (if present): `bun run test`, `bun run lint`, `bun run typecheck`

## Repo map (confirm/update)

- UI entry: `src/main.tsx`
- Components: `src/components/`
- Core logic/types: `src/lib/`

## Deploy

There is a deploy script (see `scripts/deploy.sh`) and a separate public repo for built output.

## Required workflow for every task

1) Repo study: identify entry points + relevant modules, list files to touch.
2) Plan: smallest vertical slice, with acceptance criteria.
3) Implement: code + minimal tests or manual verification steps.
4) Evidence: paste command output (build/test) and note any tradeoffs.

## Security Architecture (v1.3.0+)

- **Session-key encryption**: Ephemeral AES-GCM-256 key (non-exportable) encrypts sensitive state
- **Auto-clear**: Plaintext mnemonic cleared from UI immediately after QR generation
- **Encrypted cache**: Only ciphertext stored in React state; key lives in memory only
- **Lock/Clear**: Manual cleanup destroys session key + clears all state
- **Lifecycle**: Session key auto-destroyed on page close/refresh

## Module: src/lib/sessionCrypto.ts

- `getSessionKey()` - Generates/returns non-exportable AES-GCM key (idempotent)
- `encryptJsonToBlob(obj)` - Encrypts to {v, alg, iv_b64, ct_b64}
- `decryptBlobToJson(blob)` - Decrypts back to original object
- `destroySessionKey()` - Drops key reference for GC
- Test: `await window.runSessionCryptoTest()` (DEV only)