3552db50c2
- AGE encryption with master password model - Core commands: init, show, insert, edit, generate, rm, mv, cp, find, grep, ls - Git integration for version control - Clipboard support (X11 and Wayland) - Secure password generation - Backup and restore functionality - Comprehensive security features - Complete documentation
113 lines
3.0 KiB
Markdown
113 lines
3.0 KiB
Markdown
# Code Structure
|
|
|
|
This document explains the organization of PassAGE's source code.
|
|
|
|
## File Overview
|
|
|
|
### Core Application Files
|
|
|
|
- **`main.go`** - Application entry point
|
|
- Parses command-line arguments
|
|
- Routes commands to appropriate handlers
|
|
- Displays usage and version information
|
|
|
|
- **`commands.go`** - Command implementations
|
|
- All user-facing commands (init, show, insert, edit, generate, etc.)
|
|
- Command-line flag parsing
|
|
- User interaction and output formatting
|
|
|
|
- **`store.go`** - Core store operations
|
|
- Password store directory management
|
|
- Master password handling (hashing, verification)
|
|
- AGE encryption/decryption functions
|
|
- File I/O operations
|
|
|
|
### Security & Utilities
|
|
|
|
- **`security.go`** - Security utilities
|
|
- Path traversal protection
|
|
- Input validation and sanitization
|
|
- Resource limits (file size, password length)
|
|
- Secure temporary file creation
|
|
|
|
- **`memory.go`** - Secure memory management
|
|
- `SecureBytes` type for sensitive data
|
|
- Memory clearing functions
|
|
- Prevents passwords from lingering in memory
|
|
|
|
- **`clipboard.go`** - Clipboard operations
|
|
- Copy passwords to clipboard
|
|
- Auto-clear clipboard after timeout
|
|
- Signal handling for cleanup
|
|
|
|
- **`backup.go`** - Backup and restore
|
|
- Create compressed backups with checksums
|
|
- Restore backups with integrity verification
|
|
- Path validation during restore
|
|
|
|
## Code Flow
|
|
|
|
### Initialization Flow
|
|
1. User runs `passage init`
|
|
2. `cmdInit()` prompts for master password
|
|
3. Password is hashed with Argon2id
|
|
4. Hash stored in `.master-pass` file
|
|
5. Store directory created with proper permissions
|
|
|
|
### Password Storage Flow
|
|
1. User runs `passage insert example.com`
|
|
2. `getMasterPasswordForOperation()` prompts and verifies master password
|
|
3. Password stored in `SecureBytes` (cleared after use)
|
|
4. Password encrypted with AGE Scrypt encryption
|
|
5. Encrypted file saved as `example.com.passage`
|
|
|
|
### Password Retrieval Flow
|
|
1. User runs `passage show example.com`
|
|
2. Master password verified
|
|
3. Encrypted file decrypted using AGE
|
|
4. Decrypted content displayed or copied to clipboard
|
|
5. Master password cleared from memory
|
|
|
|
## Key Design Decisions
|
|
|
|
### Master Password Model
|
|
- Single password protects all passwords
|
|
- Verified using Argon2id hash (memory-hard)
|
|
- Never stored in plaintext
|
|
- Required for all operations
|
|
|
|
### File Organization
|
|
- All files in root directory (simple, standard for Go CLI tools)
|
|
- Clear separation of concerns by file
|
|
- Each file has a specific purpose
|
|
|
|
### Security Features
|
|
- Constant-time password comparisons
|
|
- Secure memory clearing
|
|
- Path traversal protection
|
|
- Resource limits to prevent DoS
|
|
- File permissions (0600/0700)
|
|
|
|
### Error Handling
|
|
- Clear error messages
|
|
- Graceful fallbacks where appropriate
|
|
- Proper cleanup on errors
|
|
|
|
## Dependencies
|
|
|
|
- **filippo.io/age** - AGE encryption library
|
|
- **golang.org/x/crypto** - Argon2id hashing
|
|
- **golang.org/x/term** - Secure password input
|
|
|
|
## Testing
|
|
|
|
Run tests with:
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
Run with race detector:
|
|
```bash
|
|
go test -race ./...
|
|
```
|