PassAGE/README.md

PassAGE

A modern password manager using AGE encryption.

Quick Links: Installation • Quick Start • Commands • Security • Contributing

Features

• AGE encryption: Uses AGE (Actually Good Encryption) for secure password storage
• 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: 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

Prerequisites

• 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

# Clone the repository
git clone https://git.fraggle.lol/fraggle/PassAGE.git
cd PassAGE

# Download dependencies
go mod download

# Build
go build -o passage .

# Or use Makefile
make build

Installation:

# System-wide installation
sudo make install

# User installation (no sudo required)
make install-user

Or install directly with go:

go install git.fraggle.lol/fraggle/PassAGE@latest

Build Options

For production builds, you may want to use additional flags:

# Build with version information
go build -ldflags "-X main.version=$(git describe --tags --always --dirty)" -o passage

# Build with trimmed paths (for reproducible builds)
go build -trimpath -o passage

# Build with race detector (for testing)
go build -race -o passage

# Build optimized binary (smaller, faster)
go build -ldflags "-s -w" -trimpath -o passage

Build flags explained:

• -ldflags "-X main.version=..." - Inject version information at build time
• -trimpath - Remove file system paths for reproducible builds
• -race - Enable race detector (for debugging concurrency issues)
• -ldflags "-s -w" - Strip debug symbols and disable DWARF generation (smaller binary)

Install Binary

Pre-built binaries may be available from the releases page.

Quick Start

1. Initialize the password store

Initialize the password store with a master password:

passage init

This will prompt you to:

• Enter a master password (used to encrypt/decrypt all passwords)
• Confirm the master password

The master password is required for all operations.

2. Add a password

passage insert example.com

3. Retrieve a password

passage show example.com

4. Generate a password

passage generate example.com 32

Usage

Commands

• passage init [--path=subfolder] - Initialize password store with master password
• passage [ls] [subfolder] - List passwords
• passage find pass-names... - Find passwords by name
• passage [show] [--clip[=line-number]] pass-name - Show password
• passage grep search-string - Search within passwords
• passage insert [--multiline] [--force] pass-name - Insert password
• passage edit pass-name - Edit password
• passage generate [--no-symbols] [--clip] [--in-place | --force] pass-name [pass-length] - Generate password
• passage rm [--recursive] [--force] pass-name - Remove password
• passage mv [--force] old-path new-path - Move/rename password
• passage cp [--force] old-path new-path - Copy password
• passage git git-command-args... - Run git commands
• passage help - Show help
• passage version - Show version

Environment Variables

passage respects the following environment variables:

• PASSAGE_DIR - Path to password store (default: ~/.passage-store)

  export PASSAGE_DIR=~/my-passwords
  

• PASSAGE_CLIP_TIME - Time in seconds to keep password in clipboard before auto-clearing (default: 10)

  export PASSAGE_CLIP_TIME=30  # Keep in clipboard for 30 seconds
  

• PASSAGE_GENERATED_LENGTH - Default length for generated passwords (default: 25)

  export PASSAGE_GENERATED_LENGTH=32  # Generate 32-character passwords by default
  

• EDITOR - Editor to use for passage edit command (default: vi)

  export EDITOR=nano  # Use nano instead of vi
  

Note: For complete documentation of all environment variables, see the manpage or run man passage after installation.

Git Integration

Initialize git repository:

passage git init

All password operations automatically commit to git (if initialized).

Security

IMPORTANT: PassAGE uses a master password model. Every operation requires the master password set during passage init.

Quick Security Overview

• Master password: Single password protects all stored passwords (never stored in plaintext)
• AGE Scrypt encryption: Industry-standard passphrase encryption
• Argon2id verification: Master password verified using Argon2id hash (memory-hard, resistant to brute force)
• File permissions: Store directory uses 0700, sensitive files use 0600

Best Practices

1. Choose a strong master password (it cannot be recovered if forgotten)
2. Use full disk encryption
3. Back up your password store directory
4. See SECURITY.md for detailed security information

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Documentation

• INSTALL.md - Detailed installation instructions and troubleshooting
• SECURITY.md - Security implementation details
• CONTRIBUTING.md - How to contribute to the project
• Manpage - Run man passage after installation (source: passage.1.md)

Project Structure

PassAGE/
├── main.go              # Entry point, command routing
├── commands.go          # Command implementations
├── store.go             # Core store operations
├── security.go          # Security utilities (path validation, etc.)
├── memory.go            # Secure memory management
├── clipboard.go         # Clipboard operations (Linux X11/Wayland)
├── backup.go            # Backup/restore functionality
├── go.mod               # Go module definition
├── Makefile             # Build and install targets
├── passage.1.md         # Manpage source
└── *.md                 # Documentation files

License

This project uses AGE encryption. See LICENSE file for details.