app_spec.txt

<project_specification>
  <project_name>QuickKee</project_name>

  <overview>
    QuickKee is a Chrome browser extension that integrates with KeePass databases for password management.
    It allows users to autofill login forms, generate and save passwords, and manage their entire KeePass
    database directly from the browser. The extension supports both local .kdbx files and cloud storage
    (Dropbox, Google Drive), with sync capabilities and comprehensive security features including phishing
    detection and certificate warnings. Open source and free for everyone.
  </overview>

  <technology_stack>
    <frontend>
      <framework>React</framework>
      <language>TypeScript</language>
      <styling>CSS Modules or Styled Components</styling>
      <package_manager>Yarn</package_manager>
    </frontend>
    <backend>
      <type>Chrome Extension (Manifest V3)</type>
      <service_worker>TypeScript</service_worker>
      <kdbx_library>kdbxweb</kdbx_library>
    </backend>
    <storage>
      <local>Chrome Storage API, IndexedDB</local>
      <cloud>Dropbox API, Google Drive API</cloud>
      <database_format>KeePass .kdbx</database_format>
    </storage>
  </technology_stack>

  <prerequisites>
    <environment_setup>
      - Node.js 18+
      - Yarn package manager
      - Chrome browser for testing
      - Chrome Extensions Developer Mode enabled
    </environment_setup>
  </prerequisites>

  <feature_count>118</feature_count>

  <security_and_access_control>
    <authentication>
      <method>KeePass database master password and/or key file</method>
      <session_timeout>Configurable auto-lock timer (user-selectable per session)</session_timeout>
      <unlock_flow>Popup prompts for database location, master password, and optional key file</unlock_flow>
    </authentication>
    <security_features>
      <clipboard_protection>Auto-clear clipboard after configurable duration</clipboard_protection>
      <phishing_detection>Integration with known phishing site lists, show warnings</phishing_detection>
      <certificate_warnings>Detect and warn on insecure/invalid SSL certificates</certificate_warnings>
      <password_visibility>Passwords hidden by default with reveal toggle</password_visibility>
      <manual_lock>Lock Now button available at all times</manual_lock>
    </security_features>
    <data_isolation>
      <locked_state>No credential data accessible when database is locked</locked_state>
      <memory_protection>Sensitive data cleared from memory on lock</memory_protection>
    </data_isolation>
  </security_and_access_control>

  <core_features>
    <database_unlock_lock>
      - Select local .kdbx file via file picker
      - Connect to cloud storage (Dropbox, Google Drive) via OAuth
      - Enter master password
      - Select key file (optional)
      - Custom auto-lock timer per session
      - Unlock database
      - Lock Now button
      - Auto-lock on timer expiration
      - Locked state UI (no credential info visible)
      - Remember last used database location
      - Guide new users to create database
      - Database creation wizard (location selection, password setup)
    </database_unlock_lock>

    <popup_site_with_saved_password>
      - Detect if current site has saved credentials
      - List multiple logins for same site
      - Copy password button per entry
      - Copy username button per entry
      - Copy custom KeePass fields
      - Keyboard shortcut Ctrl+C to copy password
      - Keyboard shortcut Ctrl+B to copy username
      - Tab key cycles through credential list
      - Password hidden by default (dots/asterisks)
      - Eye icon toggle to reveal password
      - "Copied!" indicator on copy action
      - Clipboard clear countdown timer display
      - Auto-clear clipboard after timer
      - Notes icon for entries with notes
      - View/edit notes modal
      - Password expiration warning indicator
      - Phishing site warning banner
      - Insecure certificate warning banner
    </popup_site_with_saved_password>

    <popup_site_without_saved_password>
      - Generate password button
      - Settings cog button for generation rules
      - Password rules customization modal
      - Preview generated password
      - Regenerate password button
      - Copy generated password
      - Auto-capture current URL
      - Auto-capture page title
      - Username input field
      - Save new credential entry
      - Success confirmation after save
    </popup_site_without_saved_password>

    <autofill>
      - Detect login form fields on page
      - Show inline dropdown on form field focus (similar to Chrome autofill)
      - List available credentials in dropdown
      - Fill all matching fields on selection (username + password)
      - Handle multiple saved logins for same site
      - Enable/disable autofill in settings
      - Integrate with Chrome Autofill API if possible
    </autofill>

    <side_panel_database_browser>
      - Open database view in Chrome side panel
      - Folder/group tree navigation (KeePass structure)
      - List entries within selected folder
      - Search entries across entire database
      - View entry details
      - Create new entry
      - Edit existing entry
      - Delete entry with confirmation
      - Create new folder/group
      - Edit folder/group
      - Delete folder/group
      - Drag and drop entries between folders
    </side_panel_database_browser>

    <cloud_sync>
      - Connect Dropbox via OAuth
      - Connect Google Drive via OAuth
      - Manual sync button
      - Automatic sync on configurable interval
      - Sync status indicator (icon/badge)
      - Last synced timestamp display
      - Sync in progress indicator
      - Sync failed error indicator
      - Conflict detection on sync
      - Conflict resolution UI
      - Per-item conflict resolution (choose local or cloud version)
    </cloud_sync>

    <extension_icon>
      - Default icon state (gray/neutral)
      - Colored icon when current site has saved credentials
      - Disabled/grayed icon on non-site tabs (new tab, settings, extensions)
      - Icon updates on tab navigation
    </extension_icon>

    <settings>
      - Settings page accessible from popup
      - Default password generation rules configuration
      - Clipboard clear duration setting
      - Cloud sync interval setting
      - Auto-lock duration setting
      - Autofill popup enable/disable toggle
      - Theme selection (light, dark, system)
      - Save settings button
      - Reset to defaults button
    </settings>

    <theme_and_ui>
      - Light theme
      - Dark theme
      - System preference auto-detection
      - Theme switching without page reload
      - Consistent styling across popup, side panel, and settings
      - Responsive layout within extension constraints
    </theme_and_ui>
  </core_features>

  <database_schema>
    <note>QuickKee uses KeePass .kdbx file format via kdbxweb library. No custom database schema needed.</note>
    <kdbx_structure>
      <groups>Hierarchical folders containing entries</groups>
      <entries>
        - Title
        - Username
        - Password
        - URL
        - Notes
        - Custom fields (key-value pairs)
        - Created timestamp
        - Modified timestamp
        - Expiration date
        - Icon
      </entries>
    </kdbx_structure>
    <extension_storage>
      <chrome_storage_local>
        - Last used database location
        - User preferences/settings
        - Theme preference
        - Password generation rules
        - Clipboard timer duration
        - Sync interval
        - Auto-lock duration
      </chrome_storage_local>
      <chrome_storage_session>
        - Unlocked database state
        - Decrypted database in memory (encrypted at rest)
        - Current session lock timer
      </chrome_storage_session>
    </extension_storage>
  </database_schema>

  <api_endpoints_summary>
    <note>As a Chrome extension, QuickKee uses internal messaging and Chrome APIs rather than REST endpoints.</note>
    <internal_messages>
      <database>
        - UNLOCK_DATABASE (password, keyFile, location)
        - LOCK_DATABASE
        - GET_DATABASE_STATUS
        - CREATE_DATABASE (location, password, keyFile)
        - SYNC_DATABASE
        - GET_SYNC_STATUS
      </database>
      <entries>
        - GET_ENTRIES_FOR_URL (url)
        - GET_ALL_ENTRIES
        - GET_ENTRY (id)
        - CREATE_ENTRY (entry)
        - UPDATE_ENTRY (id, entry)
        - DELETE_ENTRY (id)
        - SEARCH_ENTRIES (query)
      </entries>
      <groups>
        - GET_GROUPS
        - CREATE_GROUP (parentId, name)
        - UPDATE_GROUP (id, name)
        - DELETE_GROUP (id)
        - MOVE_ENTRY (entryId, groupId)
      </groups>
      <password>
        - GENERATE_PASSWORD (rules)
        - GET_PASSWORD_RULES
        - SET_PASSWORD_RULES (rules)
      </password>
      <settings>
        - GET_SETTINGS
        - UPDATE_SETTINGS (settings)
        - RESET_SETTINGS
      </settings>
      <clipboard>
        - COPY_TO_CLIPBOARD (text, type)
        - CLEAR_CLIPBOARD
        - GET_CLIPBOARD_TIMER
      </clipboard>
      <security>
        - CHECK_PHISHING (url)
        - CHECK_CERTIFICATE (url)
        - GET_PASSWORD_EXPIRATION_STATUS (entryId)
      </security>
    </internal_messages>
    <external_apis>
      <dropbox>OAuth 2.0 for authentication, Files API for read/write</dropbox>
      <google_drive>OAuth 2.0 for authentication, Drive API v3 for read/write</google_drive>
      <phishing_lists>Integration with public phishing URL databases (e.g., OpenPhish, PhishTank)</phishing_lists>
    </external_apis>
  </api_endpoints_summary>

  <ui_layout>
    <popup>
      <locked_state>
        - Database file selector (local or cloud)
        - Password input field
        - Key file selector
        - Auto-lock timer dropdown
        - Unlock button
        - Create new database button
      </locked_state>
      <unlocked_site_with_credentials>
        - Warning banners (phishing, certificate) at top if applicable
        - List of matching credentials
        - Each item shows: title, username, copy buttons, notes icon
        - Password hidden with reveal toggle
        - Keyboard shortcut hints
        - Lock button in header
      </unlocked_site_with_credentials>
      <unlocked_site_without_credentials>
        - Generate password section
        - Generated password display (hidden by default)
        - Regenerate and settings buttons
        - Save credential form (URL, title, username auto-filled)
        - Save button
        - Lock button in header
      </unlocked_site_without_credentials>
      <non_site_tab>
        - Extension icon disabled
        - Popup shows "Navigate to a website to use QuickKee"
      </non_site_tab>
    </popup>
    <side_panel>
      <header>
        - Search bar
        - Lock button
        - Settings button
        - Sync status indicator
      </header>
      <navigation>
        - Collapsible folder tree (left or top)
        - Breadcrumb trail
      </navigation>
      <content>
        - Entry list for selected folder
        - Entry detail view (expandable or modal)
        - Create/edit entry form
      </content>
    </side_panel>
    <autofill_dropdown>
      - Small inline dropdown near form field
      - List of matching credentials (icon, title, username)
      - Click to fill all fields
    </autofill_dropdown>
    <settings_page>
      - Full-page settings (opens in new tab)
      - Sections for: General, Security, Password Generation, Sync, Theme
      - Save and Reset buttons
    </settings_page>
  </ui_layout>

  <design_system>
    <color_palette>
      <light_theme>
        - Primary: #4A90D9 (KeePass-inspired blue)
        - Background: #FFFFFF
        - Surface: #F5F5F5
        - Text: #333333
        - Success: #4CAF50
        - Warning: #FF9800
        - Error: #F44336
      </light_theme>
      <dark_theme>
        - Primary: #64B5F6
        - Background: #1E1E1E
        - Surface: #2D2D2D
        - Text: #E0E0E0
        - Success: #66BB6A
        - Warning: #FFA726
        - Error: #EF5350
      </dark_theme>
    </color_palette>
    <typography>
      <font_family>System font stack (-apple-system, BlinkMacSystemFont, Segoe UI, Roboto)</font_family>
      <sizes>
        - Small: 12px
        - Body: 14px
        - Heading: 16px
      </sizes>
    </typography>
    <spacing>
      <unit>4px base unit</unit>
      <popup_width>350px</popup_width>
      <side_panel_min_width>300px</side_panel_min_width>
    </spacing>
    <icons>
      <style>Outlined, minimal icons (consider Lucide or similar)</style>
    </icons>
  </design_system>

  <implementation_steps>
    <step number="1">
      <title>Project Setup and Extension Scaffold</title>
      <tasks>
        - Initialize project with Yarn and TypeScript
        - Set up Chrome Extension Manifest V3 structure
        - Configure build pipeline (Webpack/Vite for extension)
        - Set up React for popup, side panel, and settings pages
        - Install kdbxweb library
        - Create basic extension structure (popup, background service worker, content scripts)
      </tasks>
    </step>
    <step number="2">
      <title>Database Core - Unlock/Lock Flow</title>
      <tasks>
        - Implement local file picker for .kdbx files
        - Integrate kdbxweb for database parsing
        - Implement password and key file authentication
        - Create unlock/lock state management
        - Implement auto-lock timer
        - Create locked state UI
      </tasks>
    </step>
    <step number="3">
      <title>Popup - Basic Functionality</title>
      <tasks>
        - Build popup UI for locked state
        - Build popup UI for site with credentials
        - Build popup UI for site without credentials
        - Implement credential detection for current tab URL
        - Implement copy to clipboard with auto-clear
        - Add keyboard shortcuts (Ctrl+C, Ctrl+B, Tab)
      </tasks>
    </step>
    <step number="4">
      <title>Password Generation</title>
      <tasks>
        - Create password generator with configurable rules
        - Build generation rules UI
        - Save default rules to settings
        - Integrate with save new credential flow
      </tasks>
    </step>
    <step number="5">
      <title>Autofill</title>
      <tasks>
        - Create content script for form detection
        - Build inline autofill dropdown UI
        - Implement field filling logic
        - Handle multiple credentials per site
        - Add enable/disable toggle
      </tasks>
    </step>
    <step number="6">
      <title>Side Panel - Database Browser</title>
      <tasks>
        - Set up Chrome side panel API
        - Build folder tree navigation
        - Implement entry list view
        - Create entry detail view
        - Implement CRUD operations for entries
        - Implement CRUD operations for groups
        - Add search functionality
      </tasks>
    </step>
    <step number="7">
      <title>Cloud Storage Integration</title>
      <tasks>
        - Implement Dropbox OAuth flow
        - Implement Google Drive OAuth flow
        - Create cloud file picker UI
        - Implement sync mechanism
        - Build conflict detection and resolution UI
        - Add sync status indicators
      </tasks>
    </step>
    <step number="8">
      <title>Security Features</title>
      <tasks>
        - Integrate phishing site detection
        - Implement certificate checking
        - Add warning UI components
        - Implement password expiration checking
        - Add security warning indicators
      </tasks>
    </step>
    <step number="9">
      <title>Settings and Themes</title>
      <tasks>
        - Build settings page
        - Implement all user preferences
        - Create theme system (light, dark, system)
        - Add settings persistence
      </tasks>
    </step>
    <step number="10">
      <title>Extension Icon States</title>
      <tasks>
        - Create icon variants (default, active, disabled)
        - Implement icon state updates on tab change
        - Handle non-site tabs
      </tasks>
    </step>
    <step number="11">
      <title>New Database Creation</title>
      <tasks>
        - Build database creation wizard
        - Implement save to local file
        - Implement save to cloud storage
        - Guide first-time users
      </tasks>
    </step>
    <step number="12">
      <title>Polish and Testing</title>
      <tasks>
        - Comprehensive testing across all features
        - Performance optimization
        - Accessibility review
        - UI polish and consistency
        - Error handling improvements
        - Documentation
      </tasks>
    </step>
  </implementation_steps>

  <success_criteria>
    <functionality>
      - Users can unlock/lock a KeePass database (local or cloud)
      - Users can autofill credentials on login forms
      - Users can generate, save, and copy passwords
      - Users can browse, search, and manage their entire database
      - Cloud sync works reliably with conflict resolution
      - Security warnings display appropriately
    </functionality>
    <user_experience>
      - Extension feels fast and responsive
      - UI is intuitive for both KeePass veterans and newcomers
      - Keyboard shortcuts work reliably
      - Clipboard security features work transparently
      - Theme matches user preference automatically
    </user_experience>
    <technical_quality>
      - No console errors during normal operation
      - Graceful error handling for all edge cases
      - Secure handling of sensitive data (passwords never logged, cleared from memory)
      - Works on Chrome stable release
    </technical_quality>
    <design_polish>
      - Consistent visual design across all UI surfaces
      - Smooth transitions and feedback
      - Clear visual hierarchy
      - Accessible to keyboard and screen reader users
    </design_polish>
  </success_criteria>
</project_specification>