# 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 ./...
```