# gateway-of-last-resort/keyward architecture

> Architecture diagram of the GitHub repository gateway-of-last-resort/keyward, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gateway-of-last-resort/keyward
- Repository: https://github.com/gateway-of-last-resort/keyward

## Overview

Keyward is a terminal SSH-setup manager with both an interactive Bubble Tea UI and headless CLI. The main workflow loads SSH keys and config, then lets users inspect and manage keys, edit hosts, audit security, browse known hosts, and create or restore encrypted backups. The graph emphasizes documented capabilities and sampled call paths; unsampled screens and integrations are included only where their paths are explicit, and links without visible evidence are omitted.

Main entry points: [`internal/ui/model.go`](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/model.go) (Interactive shell), [`internal/cli/cli.go`](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/cli/cli.go) (CLI router), [`cmd/keyward/main.go`](https://github.com/gateway-of-last-resort/keyward/blob/main/cmd/keyward/main.go) (Application entry), [`internal/audit/checks.go`](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/audit/checks.go) (Security audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main["Application entry<br/>[main.go]"]
  node_cli["CLI router<br/>[cli.go]"]
  node_environment["SSH environment<br/>[cli.go]"]
end

subgraph group_experience["User experience"]
  node_tui["Interactive shell<br/>[model.go]"]
  node_keylist["Key inventory<br/>[keys.go]"]
  node_keydetail["Key details<br/>[detail.go]"]
  node_configui["Config editor<br/>[config.go]"]
  node_auditui["Audit screen<br/>[audit.go]"]
  node_knownui["Known-hosts screen<br/>[knownhosts.go]"]
  node_backupui["Backup screen<br/>[backup.go]"]
  node_setup["Vault setup<br/>[setup.go]"]
  node_settings["Settings<br/>[settings.go]"]
end

subgraph group_ssh["SSH management"]
  node_keyops["Key operations<br/>[generate.go]"]
  node_config["SSH config<br/>[parser.go]"]
  node_knownhosts["Known hosts<br/>[knownhosts.go]"]
  node_agent["SSH agent<br/>[agent.go]"]
end

subgraph group_security["Security and vault"]
  node_audit["Security audit<br/>[checks.go]"]
  node_vault[("Encrypted metadata<br/>[storage.go]")]
  node_backup["Encrypted backups<br/>[backup.go]"]
  node_crypto["Cryptography<br/>[crypto.go]"]
  node_masterkey["Master key<br/>[masterkey.go]"]
end

node_user(("Operator"))

node_user -->|"launches"| node_main
node_main -->|"routes arguments"| node_cli
node_main -->|"loads environment"| node_environment
node_main -->|"runs audit"| node_audit
node_main -->|"starts interface"| node_tui
node_cli -->|"loads shared state"| node_environment
node_environment -->|"parses keys"| node_keyops
node_environment -->|"parses config"| node_config
node_tui -.->|"shows inventory"| node_keylist
node_tui -.->|"routes screen"| node_configui
node_tui -.->|"routes screen"| node_auditui
node_tui -.->|"routes screen"| node_knownui
node_tui -.->|"routes screen"| node_backupui
node_tui -->|"initializes vault"| node_setup
node_tui -.->|"routes screen"| node_settings
node_keylist -.->|"opens details"| node_keydetail
node_keydetail -.->|"rotates keys"| node_keyops
node_keydetail -.->|"adds key"| node_agent
node_keydetail -->|"reads metadata"| node_vault
node_configui -.->|"edits config"| node_config
node_auditui -.->|"presents findings"| node_audit
node_knownui -.->|"manages entries"| node_knownhosts
node_backupui -->|"creates or restores"| node_backup
node_backup -->|"encrypts archive"| node_crypto
node_vault -->|"encrypts metadata"| node_crypto
node_setup -.->|"sets password"| node_masterkey
node_settings -.->|"changes password"| node_masterkey
node_audit -->|"checks directives"| node_config
node_audit -->|"checks keys"| node_keyops
node_cli -->|"audit command"| node_audit
node_cli -->|"backup command"| node_backup
node_cli -->|"agent commands"| node_agent
node_cli -->|"imports keys"| node_keyops
node_tui -->|"updates metadata"| node_vault

click node_main "https://github.com/gateway-of-last-resort/keyward/blob/main/cmd/keyward/main.go"
click node_cli "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/cli/cli.go"
click node_environment "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/cli/cli.go"
click node_tui "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/model.go"
click node_keylist "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/keys.go"
click node_keydetail "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/detail.go"
click node_configui "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/config.go"
click node_auditui "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/audit.go"
click node_knownui "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/knownhosts.go"
click node_backupui "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/backup.go"
click node_setup "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/setup.go"
click node_settings "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/settings.go"
click node_keyops "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/keys/generate.go"
click node_config "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/config/parser.go"
click node_knownhosts "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/knownhosts/knownhosts.go"
click node_agent "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/agent/agent.go"
click node_audit "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/audit/checks.go"
click node_vault "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/storage/storage.go"
click node_backup "https://github.com/gateway-of-last-resort/keyward/blob/main/internal/storage/backup.go"
click node_crypto "https://github.com/gateway-of-last-resort/keyward/blob/main/pkg/crypto/crypto.go"
click node_masterkey "https://github.com/gateway-of-last-resort/keyward/blob/main/pkg/crypto/masterkey.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_environment toneBlue
class node_tui,node_keylist,node_keydetail,node_configui,node_auditui,node_knownui,node_backupui,node_setup,node_settings toneAmber
class node_keyops,node_config,node_knownhosts,node_agent toneMint
class node_audit,node_vault,node_backup,node_crypto,node_masterkey toneRose
class node_user toneIndigo
```

## Components

### Entry points

- [Application entry](https://github.com/gateway-of-last-resort/keyward/blob/main/cmd/keyward/main.go): `cmd/keyward/main.go`
- [CLI router](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [SSH environment](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/cli/cli.go): `internal/cli/cli.go`

### User experience

- [Interactive shell](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/model.go): `internal/ui/model.go`
- [Key inventory](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/keys.go): `internal/ui/keys.go`
- [Key details](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/detail.go): `internal/ui/detail.go`
- [Config editor](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/config.go): `internal/ui/config.go`
- [Audit screen](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/audit.go): `internal/ui/audit.go`
- [Known-hosts screen](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/knownhosts.go): `internal/ui/knownhosts.go`
- [Backup screen](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/backup.go): `internal/ui/backup.go`
- [Vault setup](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/setup.go): `internal/ui/setup.go`
- [Settings](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/ui/settings.go): `internal/ui/settings.go`

### SSH management

- [Key operations](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/keys/generate.go): `internal/keys/generate.go`
- [SSH config](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/config/parser.go): `internal/config/parser.go`
- [Known hosts](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/knownhosts/knownhosts.go): `internal/knownhosts/knownhosts.go`
- [SSH agent](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/agent/agent.go): `internal/agent/agent.go`

### Security and vault

- [Security audit](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/audit/checks.go): `internal/audit/checks.go`
- [Encrypted metadata](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Encrypted backups](https://github.com/gateway-of-last-resort/keyward/blob/main/internal/storage/backup.go): `internal/storage/backup.go`
- [Cryptography](https://github.com/gateway-of-last-resort/keyward/blob/main/pkg/crypto/crypto.go): `pkg/crypto/crypto.go`
- [Master key](https://github.com/gateway-of-last-resort/keyward/blob/main/pkg/crypto/masterkey.go): `pkg/crypto/masterkey.go`

### Other components

- **Operator**

## Connections

- Operator → Application entry: launches (evidence: `README.md`)
- Application entry → CLI router: routes arguments (evidence: `cmd/keyward/main.go`)
- Application entry → SSH environment: loads environment (evidence: `cmd/keyward/main.go`)
- Application entry → Security audit: runs audit (evidence: `cmd/keyward/main.go`)
- Application entry → Interactive shell: starts interface (evidence: `cmd/keyward/main.go`)
- CLI router → SSH environment: loads shared state (evidence: `internal/cli/cli.go`)
- SSH environment → Key operations: parses keys (evidence: `internal/cli/cli.go`)
- SSH environment → SSH config: parses config (evidence: `internal/cli/cli.go`)
- Interactive shell → Key inventory: shows inventory
- Interactive shell → Config editor: routes screen
- Interactive shell → Audit screen: routes screen
- Interactive shell → Known-hosts screen: routes screen
- Interactive shell → Backup screen: routes screen
- Interactive shell → Vault setup: initializes vault (evidence: `internal/ui/model.go`)
- Interactive shell → Settings: routes screen
- Key inventory → Key details: opens details
- Key details → Key operations: rotates keys
- Key details → SSH agent: adds key
- Key details → Encrypted metadata: reads metadata (evidence: `internal/ui/detail.go`)
- Config editor → SSH config: edits config
- Audit screen → Security audit: presents findings
- Known-hosts screen → Known hosts: manages entries
- Backup screen → Encrypted backups: creates or restores (evidence: `internal/ui/backup.go`)
- Encrypted backups → Cryptography: encrypts archive (evidence: `internal/storage/backup.go`)
- Encrypted metadata → Cryptography: encrypts metadata (evidence: `internal/storage/storage.go`)
- Vault setup → Master key: sets password
- Settings → Master key: changes password
- Security audit → SSH config: checks directives (evidence: `internal/audit/checks.go`)
- Security audit → Key operations: checks keys
- CLI router → Security audit: audit command
- CLI router → Encrypted backups: backup command
- CLI router → SSH agent: agent commands
- CLI router → Key operations: imports keys
- Interactive shell → Encrypted metadata: updates metadata (evidence: `internal/ui/model.go`)
