# onepasswd Project Memory

## Project Overview
onepasswd is a secure command-line password manager with encryption, GitHub sync, and extensive export capabilities. It provides a simple yet powerful way to manage passwords across different platforms.

## Technology Stack
- **Language**: Python 3.6+
- **CLI Framework**: Click
- **Encryption**: PyCryptodome (AES-ECB, ECC authentication)
- **GitHub Integration**: PyGithub
- **Web UI**: Flask (optional)
- **Data Format**: JSON with AES encryption

## Key Architecture Components

### Core Modules
1. **client.py** - Main CLI entry point with all command definitions (698 lines)
2. **onepasswd.py** - Core database logic (DB, GitDB, PasswdGen classes)
3. **crypto.py** - Encryption/decryption utilities (AES, ECC)
4. **models.py** - PasswordEntry data model with v1/v2 format support
5. **config.py** - Configuration management
6. **exporters/__init__.py** - Export functionality (Chrome CSV, Apple Keychain CSV, JSON, Text)

### Data Format Evolution
- **v1 Format**: Simple keyword-based entries `{keyword: {password, info}}`
- **v2 Format**: Rich metadata with title, url, username, description, category, tags, timestamps
- Migration path: `onepasswd migrate` command handles v1→v2 conversion seamlessly

### Security Model
- Master password derives AES encryption key
- All passwords encrypted at rest
- ECC-based GitHub authentication
- No plaintext storage except during export operations

## Key Features & Commands

### Password Management
- `add [keyword]` - Generate and store new password
- `save <keyword> <password>` - Store existing password
- `get <keyword>` - Retrieve password (copies to clipboard)
- `list [keyword]` - Search/list entries with fuzzy matching
- `show <keyword>` - Display detailed entry information
- `update <keyword>` - Update entry fields (supports v2 metadata)
- `del <keyword>` - Delete entry

### Sync & Backup
- `sync` - Bidirectional GitHub sync with conflict resolution
- `init` - Initialize config and database (with optional GitHub auto-sync)
- `init-command` - Generate init command for setting up on new devices

### Export Capabilities
- `export chrome <keyword> <output>` - Export to Chrome CSV format
- `export apple <keyword> <output>` - Export to Apple Keychain CSV format
- `export json <keyword> <output>` - Export to encrypted JSON
- `export text <keyword> <output>` - Export to plaintext

### Utilities
- `enc <text>` - Encrypt arbitrary text
- `dec <cipher>` - Decrypt ciphertext
- `web` - Launch Flask web interface
- `migrate` - Batch migrate entries to v2 format
- `onepasswd-upgrade` - Upgrade database format
- `onepasswd-merge` - Merge two databases
- `onepasswd-diff` - Compare databases

## Important File Paths
- Config: `~/.onepasswd.conf` (database_file, github_token, repo_name, etc.)
- Default DB: `~/.onepasswd.db`
- Sync location: `{repo}/onepasswd.db`

## Development Guidelines

### Code Style
- Python 3.6+ compatible
- Uses Click decorators for CLI commands
- Flake8 linting configured (`.flake8`)
- Logging via custom `ltlog.py` module

### Testing
- Unit tests in `test_models.py` and `test_refactor.py`
- CI/CD via GitHub Actions (`.github/workflows/ci.yml`)
- PyPI publishing automated

### Common Patterns
1. **Database Access**: Use `DB` class with context manager or explicit `db.save()`
2. **GitHub Sync**: `GitDB` class handles authentication, upload, download, merge conflicts
3. **Encryption**: All passwords encrypted via `Crypto.encrypt()/decrypt()` with master password
4. **Entry Lookup**: `db.search(keyword)` with fuzzy matching on keyword/title/url/username

### Backward Compatibility
- Always support both v1 and v2 entry formats
- `PasswordEntry.is_v2()` checks entry format
- `PasswordEntry.to_v2()` converts v1→v2
- Migration is optional but encouraged via `migrate` command

## Current Development Branch
- Branch: `feature/export-chrome-apple`
- Status: Clean (no uncommitted changes)
- Recent work: Rich metadata support, export functionality, migration tools, quick start docs

## Known Considerations
1. **Time Module Conflict**: Fixed in recent commit - models.py had naming conflict with `time` module
2. **Delete After Sync**: Fixed issue where delete wasn't syncing properly
3. **Export Formats**: Chrome and Apple Keychain have specific CSV format requirements
4. **Master Password**: Critical for all operations - never stored, only used to derive encryption key
5. **Sync Conflicts**: Automatically detected and reported during `sync` operation

## Project Structure
```
/projects/onepasswd/
├── onepasswd/
│   ├── client.py               # Main CLI entry point
│   ├── onepasswd.py            # Core database (DB, GitDB, PasswdGen)
│   ├── crypto.py               # Encryption/decryption
│   ├── models.py               # PasswordEntry data model
│   ├── config.py               # Configuration management
│   ├── ltlog.py                # Custom logging
│   ├── web.py                  # Flask web interface
│   ├── exporters/              # Export functionality
│   └── tools/                  # Database utilities (merge, diff, upgrade, migrate)
├── templates/                  # Web UI templates
├── README.md                   # Main documentation (English)
├── CLAUDE.md                   # Project memory (AI assistant)
├── requirements.txt            # Python dependencies
└── setup.py                    # Package configuration
```

## Dependencies (requirements.txt)
```
click>=7.0
colored>=1.4.2
PyGithub>=1.45
pycryptodome>=3.9.4
pyperclip>=1.7.0
requests>=2.22.0
Flask>=1.1.1
```

## Security Notes
- Never commit unencrypted databases
- GitHub token stored in plaintext config (user responsibility to secure)
- ECC key derived from master password for GitHub auth
- AES-ECB mode used (consider AES-GCM for future enhancement)
- Export operations create plaintext files (user must secure output)

## Documentation Rules
- Main: `README.md` (English, includes quick start, export guides, and migration info)
- Memory: `CLAUDE.md` (project memory for AI assistant)
- Command help: `onepasswd --help` or `onepasswd <command> --help`

**Critical Rules**:
1. **Root Directory**: Only `README.md` and `CLAUDE.md` allowed - NO other documentation files (no QUICKSTART.md, GUIDE.md, etc.)
2. **Other Docs**: Must go in `docs/` subdirectory
3. **No Process Documentation**: Never write "Changes Made", "Summary", or step-by-step process descriptions - just do the work and report results concisely
