fraggle/PassAGE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README for accurate cross-platform support

Browse Source 
- Clarify clipboard support is Linux-only (X11/Wayland)
- Remove unnecessary documentation files (SETUP.md, CODE_STRUCTURE.md, CHANGELOG.md)
- Update installation prerequisites
This commit is contained in:
fraggle 2026-01-11 18:57:11 -04:00
parent f4f7b50e98
commit 388c14426c
6 changed files with 7 additions and 265 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
CHANGELOG.md
View File

@ -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

112
CODE_STRUCTURE.md
View File

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

3
CONTRIBUTING.md
View File

@ -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?

4
INSTALL.md
View File

@ -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

11
README.md
View File

@ -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.

123
SETUP.md
View File

@ -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).