diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 168fd2c..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,19 +0,0 @@ -# Changelog - -All notable changes to PassAGE will be documented in this file. - -## [0.1.0] - Initial Release - -### Features -- PassAGE password manager using AGE encryption -- Master password model: single password protects all stored passwords -- 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 using crypto/rand - -### Technical Details -- Written in Go -- Uses filippo.io/age library for encryption -- Compatible with AGE v1 specification -- Argon2id parameters: 3 iterations, 32MB memory, 4 threads, 32-byte output diff --git a/CODE_STRUCTURE.md b/CODE_STRUCTURE.md deleted file mode 100644 index 65ada64..0000000 --- a/CODE_STRUCTURE.md +++ /dev/null @@ -1,112 +0,0 @@ -# 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 ./... -``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 577818b..03b9060 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,9 +67,6 @@ make man Requires `pandoc` or `go-md2man` to be installed. -## Repository Setup - -If you're setting up the repository for the first time, see [SETUP.md](SETUP.md) for git initialization instructions. ## Questions? diff --git a/INSTALL.md b/INSTALL.md index f1ef79a..68d8c8f 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -29,8 +29,8 @@ make install-user ## System Requirements - **Go 1.21 or later** - Required for building from source -- **Linux/macOS/Unix-like system** - Windows support may vary -- **X11 or Wayland** - For clipboard support (optional) +- **Linux/macOS/Windows** - Core functionality works on all platforms +- **xclip or wl-clipboard** (Linux only) - For clipboard support. macOS/Windows clipboard coming soon ## Build Dependencies diff --git a/README.md b/README.md index db2a0d1..2aee6aa 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ A modern password manager using AGE encryption. - **Master password model**: Single password protects all stored passwords - **Git integration**: Optional git repository support for version control - **Command-line interface**: Simple, intuitive commands -- **Cross-platform**: Works on Linux, macOS, and other Unix-like systems -- **Clipboard support**: X11 and Wayland clipboard integration +- **Cross-platform**: Core functionality works on Linux, macOS, and Windows +- **Clipboard support**: Linux (X11/Wayland). macOS and Windows clipboard support coming soon - **Secure password generation**: Cryptographically secure random password generation ## Installation @@ -21,6 +21,8 @@ A modern password manager using AGE encryption. - **Go 1.21 or later** - Required for building - **Git** - For cloning the repository - **pandoc** or **go-md2man** (optional) - For building manpages +- **xclip** or **wl-clipboard** (Linux only) - For clipboard support +- **xclip** or **wl-clipboard** (Linux only) - For clipboard support ### Build from Source @@ -198,7 +200,6 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gui - **[INSTALL.md](INSTALL.md)** - Detailed installation instructions and troubleshooting - **[SECURITY.md](SECURITY.md)** - Security implementation details -- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes - **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute to the project - **Manpage** - Run `man passage` after installation (source: `passage.1.md`) @@ -211,7 +212,7 @@ PassAGE/ ├── store.go # Core store operations ├── security.go # Security utilities (path validation, etc.) ├── memory.go # Secure memory management -├── clipboard.go # Clipboard operations +├── clipboard.go # Clipboard operations (Linux X11/Wayland) ├── backup.go # Backup/restore functionality ├── go.mod # Go module definition ├── Makefile # Build and install targets @@ -219,8 +220,6 @@ PassAGE/ └── *.md # Documentation files ``` -For detailed code structure, see [CODE_STRUCTURE.md](CODE_STRUCTURE.md). - ## License This project uses AGE encryption. See LICENSE file for details. diff --git a/SETUP.md b/SETUP.md deleted file mode 100644 index d90c18c..0000000 --- a/SETUP.md +++ /dev/null @@ -1,123 +0,0 @@ -# Repository Setup Guide - -**For Contributors:** This guide helps you set up the PassAGE repository for git. - -**Note:** This is for developers setting up the repository. End users should see [INSTALL.md](INSTALL.md). - -## Initial Git Setup - -```bash -# Initialize git repository -git init - -# Add all files (respects .gitignore) -git add . - -# Create initial commit -git commit -m "Initial commit: PassAGE password manager" - -# Add remote repository (replace with your actual repo URL) -git remote add origin https://git.fraggle.lol/fraggle/PassAGE.git - -# Push to remote -git push -u origin main -``` - -## What Gets Committed - -### Source Files (Committed) -- All `.go` files (source code) -- `go.mod` and `go.sum` (dependency management) -- `Makefile` (build configuration) -- `passage.1.md` (manpage source) -- All `.md` documentation files - -### Excluded Files (.gitignore) -- `passage` (compiled binary) -- `passage.1` (compiled manpage) -- Build artifacts -- IDE files -- Test coverage files - -## Verifying Build Readiness - -Before pushing, verify the repository can build on a clean system: - -```bash -# Clean everything -make clean -rm -rf vendor/ - -# Verify dependencies -go mod verify -go mod tidy - -# Test build -go build -o passage . - -# Test installation -make install-user - -# Clean up -make clean -``` - -## CI/CD Setup - -The repository includes a GitHub Actions workflow (`.github/workflows/build.yml`) that: -- Tests builds on Linux, macOS, and Windows -- Tests with multiple Go versions -- Verifies dependencies -- Builds release binaries - -This will run automatically on push/PR. - -## Repository Structure - -``` -passage/ -├── .gitignore # Git ignore rules -├── .github/ -│ └── workflows/ -│ └── build.yml # CI/CD workflow -├── *.go # Source code files -├── go.mod # Go module definition -├── go.sum # Dependency checksums -├── Makefile # Build and install targets -├── passage.1.md # Manpage source -├── README.md # Main documentation -├── INSTALL.md # Installation guide -├── CONTRIBUTING.md # Contribution guidelines -├── SECURITY.md # Security documentation -└── CHANGELOG.md # Version history -``` - -## Next Steps - -1. **Repository URLs are already configured:** - - All documentation points to `https://git.fraggle.lol/fraggle/PassAGE` - - Update GitHub Actions workflow if using GitHub instead - -2. **Create GitHub repository:** - - Create a new repository on GitHub - - Don't initialize with README (we already have one) - -3. **Push code:** - ```bash - git push -u origin main - ``` - -4. **Set up releases:** - - Create tags for versions: `git tag v0.1.0` - - Push tags: `git push --tags` - - GitHub Actions will build release binaries - -## Building on Any System - -The repository is designed to build on any system with: -- Go 1.21+ installed -- Standard Unix tools (make, etc.) - -Dependencies are managed through `go.mod` and will be downloaded automatically. - -For manpage building, users need `pandoc` or `go-md2man` (optional).