PassAGE/CODE_STRUCTURE.md

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:

go test ./...

Run with race detector:

go test -race ./...