feat: gpgtools configure_ssh, store_publickey, --file source, initialize (v0.7.0-v0.9.0)

- configure_ssh (0.7.0): marker-managed per-host ssh client block in
  ~/.ssh/config, idempotent, unmanaged-alias guard (exit 11)
- store_publickey (0.8.0): on-site bootstrap mirror of send_pubkey -
  run on the machine access is granted to, installs the key into the
  local authorized_keys (multi-key preserving, material dedup, 700/600,
  no possession check by design); shared --file PATH source (USB
  stick) for both store subcommands; identity block printed before
  acting (line, source, SHA-256 material digest)
- initialize (0.9.0): gnupg readiness check + install, no card
  expectations; --dry-run; initialize_yubikey step 1 shares the flow
- spec-first per SPEC 6.11/6.12: gpgtools spec.md items 2.6/2.7,
  4.1.5, 4.8, sections 10-12; 91 tests in test_gpgtools.py;
  README/registry/CHANGELOG/version pins through 0.9.0

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 08:57:30 +01:00
parent 85e8342a74
commit e9b716b399
9 changed files with 1283 additions and 74 deletions
+77 -4
View File
@@ -17,7 +17,7 @@ daedalus --list # list everything
| Script | Type | Categories | What it does |
| --- | --- | --- | --- |
| `gpgtools` | Python | gpg | YubiKey GPG/SSH helpers: initialize_yubikey (fresh machine, steps 1-4) and send_pubkey (resolve key, verify possession, append to a server) |
| `gpgtools` | Python | gpg | YubiKey GPG/SSH helpers: initialize (gnupg readiness check + install), initialize_yubikey (fresh machine, steps 1-4), send_pubkey (resolve key, verify possession, append to a server), store_publickey (install the key from the machine being granted access), configure_ssh (marker-managed per-host ssh block) |
| `hello` | Python | test | Prints a hello line and the daedalus version |
| `hello_bash` | Bash | test | Sample bash script through the shared help() interface |
@@ -36,11 +36,30 @@ table, and each description wrapped under each row.
### gpgtools
`initialize` checks that gnupg is ready on this machine and installs
what is missing — the gnupg-only half of `initialize_yubikey`, with no
card expectations. Its use is on-site: on a bare server where you are
about to run `store_publickey --fingerprint`, this is the command that
makes the gpg-dependent sources work.
```bash
daedalus gpgtools initialize # check gnupg, install when missing
daedalus gpgtools initialize --dry-run # already ready, or the install command
```
| Argument | Default | Meaning |
| --- | --- | --- |
| `--dry-run` | off | Print what would happen (already ready or the install command); change nothing |
Exit codes: `0` gnupg ready (installed or already present), `2` package
install failed or gpg still unusable after it, `3` gpg missing and no
known package manager.
`initialize_yubikey` runs the fresh-machine flow for YubiKey-backed
GPG and SSH (steps 1-4 of the wiki guide): install gnupg when missing,
check the card, fetch the public key from the card's URL field, and
write the gpg-agent SSH config. Deriving and deploying the SSH key
(steps 5-7) is server-specific and stays manual for now.
write the gpg-agent SSH config. Steps 5-7 are per-server and covered
by the subcommands below.
```bash
daedalus gpgtools # overview of the subcommands
@@ -58,7 +77,7 @@ no known package manager, `4` no card found, `5` public-key fetch did
not pair the keyring, `6` keyring unpaired and the card carries no URL.
`send_pubkey` covers guide steps 5-6 for one server: resolve the SSH
public key from one of four sources, prove possession of the private
public key from one of five sources, prove possession of the private
half with a challenge signature (the YubiKey itself signs; PIN prompts
go to the user), then append the line to the target's
`authorized_keys` — idempotent, fingerprint-checked against stores,
@@ -69,6 +88,7 @@ daedalus gpgtools send_pubkey --yubikey you@server
daedalus gpgtools send_pubkey --fingerprint <FP> you@server
daedalus gpgtools send_pubkey --url https://keys.openpgp.org/vks/v1/by-fingerprint/<FP> you@server
daedalus gpgtools send_pubkey --pubkey "ssh-ed25519 AAAA... comment" you@server
daedalus gpgtools send_pubkey --file /media/usb/yubikey_auth.pub you@server
daedalus gpgtools send_pubkey --yubikey --dry-run you@server # resolve only
```
@@ -78,6 +98,7 @@ daedalus gpgtools send_pubkey --yubikey --dry-run you@server # resolve only
| `--url URL` | — | Armored OpenPGP public key at a URL ([A] subkey is exported) |
| `--fingerprint FP` | — | Searched: local keyring → keys.openpgp.org → keyserver.ubuntu.com |
| `--pubkey LINE` | — | The literal SSH public key line |
| `--file PATH` | — | File holding the key line, e.g. a `.pub` from a USB stick (no network, no gpg) |
| `--no-verify` | verification on | Skip the proof-of-possession signature (explicit risk acceptance) |
| `--dry-run` | off | Resolve and print the key; verify and send nothing |
@@ -85,6 +106,58 @@ Additional exit codes: `7` ssh to the target failed, `8` no source
resolved a key, `10` proof-of-possession verification failed (nothing
was sent).
`store_publickey` is the mirror for the on-site bootstrap: run it on
the machine that access is being granted *to* — a server with ssh
password authentication disabled that no key authorizes yet, where
you are logged in at the console. It resolves the same five sources
and appends the key into this machine's `authorized_keys`, so the
machine holding the YubiKey can ssh in afterwards. There is no
proof-of-possession (the private half is, by design, elsewhere);
instead both resolve-and-store subcommands print an identity block —
line, source, and the key material's SHA-256 — to compare across
machines. Existing entries are preserved, nothing is duplicated, and
directory/file modes are forced to 700/600.
```bash
daedalus gpgtools store_publickey --file /media/usb/yubikey_auth.pub
daedalus gpgtools store_publickey --fingerprint <FP>
daedalus gpgtools store_publickey --pubkey "ssh-ed25519 AAAA... comment"
daedalus gpgtools store_publickey --file /media/usb/yubikey_auth.pub --dry-run # print only
```
| Argument | Default | Meaning |
| --- | --- | --- |
| sources | — | Same five sources as `send_pubkey` (exactly one required) |
| `--authorized-keys FILE` | `~/.ssh/authorized_keys` | Where to install the key |
| `--dry-run` | off | Resolve and print the key; write nothing |
Additional exit codes: `8` no source resolved a key.
`configure_ssh` covers guide step 7 for one host: it writes a
marker-managed `Host <alias>` block into the ssh client config.
Outside the markers your config is preserved byte-for-byte; re-runs
replace the block (idempotent), and an unmanaged `Host` with the same
alias is refused rather than shadowed. It never connects anywhere.
```bash
daedalus gpgtools configure_ssh --alias vault1 --hostname 203.0.113.10 --user admin
daedalus gpgtools configure_ssh --alias vault1 --dry-run # print only
daedalus gpgtools configure_ssh --alias vault1 --no-fallback # YubiKey only
```
| Argument | Default | Meaning |
| --- | --- | --- |
| `--alias NAME` | required | The ssh Host alias to configure |
| `--hostname HOST` | the alias | HostName value |
| `--user USER` | ssh's default | User value |
| `--pubkey FILE` | `~/.ssh/yubikey_auth.pub` | Primary IdentityFile (must exist) |
| `--fallback FILE` | `~/.ssh/id_ed25519` | Fallback IdentityFile, included only when it exists |
| `--no-fallback` | off | Never add a fallback IdentityFile |
| `--config PATH` | `~/.ssh/config` | Which ssh client config to edit |
Additional exit code: `11` an unmanaged `Host <alias>` exists in the
config (move it into the managed markers or rename the alias).
## Shell completion
Bash (and other shells argcomplete supports) completes script names and