# PassAGE

A modern password manager using AGE encryption.

**Repository:** [git.fraggle.lol/fraggle/PassAGE](https://git.fraggle.lol/fraggle/PassAGE)

**Quick Links:** [Installation](#installation) • [Quick Start](#quick-start) • [Commands](#usage) • [Security](#security) • [Contributing](CONTRIBUTING.md)

## 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**: Works on Linux, macOS, and other Unix-like systems
- **Clipboard support**: X11 and Wayland clipboard integration
- **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

### Build from Source

```bash
# 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:**

```bash
# System-wide installation
sudo make install

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

**Or install directly with go:**

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

#### Build Options

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

```bash
# 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](https://git.fraggle.lol/fraggle/PassAGE/releases).

## Quick Start

### 1. Initialize the password store

Initialize the password store with a master password:

```bash
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

```bash
passage insert example.com
```

### 3. Retrieve a password

```bash
passage show example.com
```

### 4. Generate a password

```bash
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`)
  ```bash
  export PASSAGE_DIR=~/my-passwords
  ```

- **PASSAGE_CLIP_TIME** - Time in seconds to keep password in clipboard before auto-clearing (default: 10)
  ```bash
  export PASSAGE_CLIP_TIME=30  # Keep in clipboard for 30 seconds
  ```

- **PASSAGE_GENERATED_LENGTH** - Default length for generated passwords (default: 25)
  ```bash
  export PASSAGE_GENERATED_LENGTH=32  # Generate 32-character passwords by default
  ```

- **EDITOR** - Editor to use for `passage edit` command (default: `vi`)
  ```bash
  export EDITOR=nano  # Use nano instead of vi
  ```

**Note:** For complete documentation of all environment variables, see the [manpage](#manpage) or run `man passage` after installation.

## Git Integration

Initialize git repository:

```bash
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](SECURITY.md) for detailed security information

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Documentation

- **[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`)

## 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
├── backup.go            # Backup/restore functionality
├── go.mod               # Go module definition
├── Makefile             # Build and install targets
├── passage.1.md         # Manpage source
└── *.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.