keyward

README

Keyward

A terminal UI for managing SSH keys, editing your ~/.ssh/config, auditing security, and keeping encrypted backups — all from one keyboard-driven screen.

Contents

• Why Keyward?
• Features
• Install
• Usage
• Security
• Building from source
• Contributing
• License

Why Keyward?

Your SSH setup is usually scattered across a pile of files: keys in ~/.ssh, hosts in ~/.ssh/config, permissions you hope are right, and no easy way to tell a strong key from a weak one. Keyward puts all of it behind a single keyboard-driven screen:

• See everything at once — every key with its type, size, fingerprint, and whether it's passphrase-protected, instead of ls-ing a directory and running ssh-keygen -l by hand.
• Know if you're safe — a graded A–F security audit flags weak keys, missing passphrases, loose file permissions, and risky config directives, each with a concrete fix.
• Edit config without breaking it — host-by-host editing with validation and byte-identical round-trip serialization: your comments, spacing, and ordering survive untouched, and the last 5 versions are backed up automatically.
• Encrypted by default — key metadata (tags, notes) and full ~/.ssh backups are encrypted at rest with a key derived from your master password.

No daemon, no config file to learn, no network calls. Just a single static binary.

Features

• Key management — discover, inspect, generate, rotate, and delete SSH keys (ed25519 / rsa), with fingerprints, comments, and per-key tags & notes.
• Config editor — edit ~/.ssh/config host-by-host with validation, comment toggling, and byte-identical round-trip serialization. Automatic backups (last 5 kept).
• Security audit — graded A–F report covering weak keys, missing passphrases, file permissions, and risky config directives, each with a concrete fix: hint.
• Encrypted backups — age-encrypted .tar.age snapshots of your ~/.ssh directory plus key metadata, restorable from within the TUI.
• Encrypted metadata vault — tags and notes are stored encrypted at rest, unlocked by your master password.

Install

Homebrew

brew install gateway-of-last-resort/tap/keyward

Download a release binary

Copy-paste this to grab the right archive for your OS/arch from the latest release, extract keyward, and put it on your PATH:

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64;; aarch64) ARCH=arm64;; esac
VER=$(curl -fsSL https://api.github.com/repos/gateway-of-last-resort/keyward/releases/latest \
      | grep -m1 '"tag_name"' | cut -d'"' -f4)
curl -fsSL "https://github.com/gateway-of-last-resort/keyward/releases/download/${VER}/keyward_${VER#v}_${OS}_${ARCH}.tar.gz" -o keyward.tar.gz
tar -xzf keyward.tar.gz keyward && sudo mv keyward /usr/local/bin/ && keyward --version

Prefer to do it by hand? Download the keyward_<version>_<os>_<arch>.tar.gz for your platform, then tar -xzf it. Verify the download against the published checksums.txt (and its cosign signature — see SECURITY.md) if you like.

[!NOTE] Some browsers (notably Safari) auto-decompress .gz downloads, leaving you with a plain keyward_..._.tar. If you only see a .tar, unpack it with tar -xf (no z).

With Go

go install github.com/gateway-of-last-resort/keyward/cmd/keyward@latest

This installs the keyward binary into $(go env GOPATH)/bin.

Usage

Just run it — no arguments launches the interactive TUI:

keyward

On first launch you set a master password; this creates an encrypted vault at ~/.keyward/master.key. Subsequent launches unlock with that password.

keyward [--version] [--help]

Navigation

Key	Action
Tab / Shift+Tab	Cycle screens: Keys → Audit → Config → Generate → Backup → Settings
↑/↓ or j/k	Move within a list
Enter	Open / confirm
Esc	Back / cancel
/	Search (Keys screen)
q	Quit (from the Keys screen)
Ctrl+C	Quit from anywhere

Per-screen actions (generate, rotate, delete, copy public key, edit config, backup/restore, change master password) are shown contextually in the footer.

[!WARNING] Rotate, delete, and restore modify real files under ~/.ssh. To experiment safely, point Keyward at a throwaway directory — run it under a sandbox HOME or change the SSH directory in Settings before trying destructive actions.

Security

Keyward encrypts metadata and backups with a master key derived from your password (argon2id → ChaCha20-Poly1305 → age identity). For the full threat model, cryptographic details, release-signature verification, and how to report a vulnerability, see SECURITY.md.

Building from source

git clone https://github.com/gateway-of-last-resort/keyward
cd keyward
go build ./cmd/keyward
go test ./...

Requires Go 1.26+. The security-sensitive core (crypto, config, storage, audit, key parsing) depends only on filippo.io/age and golang.org/x/crypto; the terminal UI layer adds the Charm stack (bubbletea, bubbles, lipgloss).

Contributing

Bug reports, feature ideas, and pull requests are welcome — see CONTRIBUTING.md for build/test/style conventions and the branch-and-PR workflow.

License

MIT