TrustVault-PWA: Instructions file for Codex

TrustVault PWA - AI Agent Instructions

Security-First Credential Manager | React 19 + TypeScript 5.7 + Vite 6 + Clean Architecture

---

Current Objectives (Nov 2025)

1. Vault Trust Hardening – Patch vault key decrypt/read bugs, wire useAutoLock, scrub decrypted state on lock, and document verification in docs/testing/TEST_STATUS.md.
2. CredOps Experience – Deliver credential CRUD UX, password generator, secure clipboard manager, search/filter, responsive dashboard, and TOTP display.
3. Passwordless & Recovery – Implement WebAuthn biometric unlock, change-master-password flows, and encrypted import/export with recovery copy.
4. Threat Intelligence & Reporting – Integrate breach detection UX, expand Vitest/integration coverage (>85%), and keep docs/security/SECURITY_AUDIT_REPORT.md current.

When implementing new functionality:

• Reference docs/guides/ROADMAP.md for prompts + validation, and update it if acceptance criteria evolve.
• Touch companion docs (README/AGENTS/CLAUDE/copilot instructions) whenever developer workflows, tooling expectations, or ownership changes.
• Record manual verification evidence in docs/testing/TEST_STATUS.md (UX) and docs/security/SECURITY_AUDIT_REPORT.md (security) before merging.

---

Architecture Overview

This is an offline-first PWA using Clean Architecture with three distinct layers:

src/
├── presentation/   # React UI, Zustand stores, MUI components
├── domain/         # Business entities & repository interfaces
├── data/           # Repository implementations, IndexedDB (Dexie)
└── core/           # Crypto utilities, auth services

Critical Rule: Dependencies flow inward only. presentation → domain ← data ← core. Domain never imports from data/presentation.

Path Aliases

Use @/ imports everywhere (configured in tsconfig.json + vite.config.ts):

import { User } from '@/domain/entities/User';
import { db } from '@/data/storage/database';
import { useAuthStore } from '@/presentation/store/authStore';
import { encrypt } from '@/core/crypto/encryption';