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
+160 -16
View File
@@ -15,6 +15,9 @@ Items are cited as `gpgtools spec item N.M`.
- [7. Files written](#7-files-written)
- [8. Testing approach](#8-testing-approach)
- [9. References](#9-references)
- [10. configure_ssh behavior](#10-configure_ssh-behavior)
- [11. store_publickey behavior](#11-store_publickey-behavior)
- [12. initialize behavior](#12-initialize-behavior)
<!-- toc-end -->
@@ -25,7 +28,10 @@ Items are cited as `gpgtools spec item N.M`.
(`~/repositories/vibe-wiki/wiki/queries/yubikey-ssh-guide.md`):
`initialize_yubikey` covers guide steps 1-4 (fresh machine ready
for GPG), `send_pubkey` covers steps 5-6 (key to a server).
Guide step 7 (per-host `~/.ssh/config`) is out of scope.
`store_publickey` covers the on-site bootstrap case (section 11):
installing the key from the machine that access is being
granted to. Guide step 7 (per-host `~/.ssh/config`) is out of
scope.
- **1.2** Hard constraint: the YubiKey's OpenPGP applet is never
written - no `gpg --card-edit`, no `keytocard`, no applet reset.
Only public card data is read; the card PIN is typed by its
@@ -38,26 +44,43 @@ Items are cited as `gpgtools spec item N.M`.
## 2. Commands
- **2.1** `daedalus gpgtools` with no subcommand prints the
overview of both subcommands and exits 0.
overview of the subcommands and exits 0.
- **2.2** `daedalus gpgtools initialize_yubikey [--dry-run]
[--gnupg-home DIR]` - prepares this machine (section 3).
- **2.3** `daedalus gpgtools send_pubkey
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE)
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE | --file PATH)
[--no-verify] [--dry-run] you@server` - resolves one SSH
public key, proves possession of the private half, appends it
to the target (section 4). The four source flags are mutually
to the target (section 4). The five source flags are mutually
exclusive and exactly one is required; `you@server` is
required.
- **2.4** `--dry-run` on either subcommand prints what would
happen and writes nothing; on `send_pubkey` it resolves and
prints the key but never verifies and never connects.
- **2.5** `daedalus gpgtools configure_ssh --alias NAME
[--hostname HOST] [--user USER] [--pubkey FILE]
[--fallback FILE | --no-fallback] [--config PATH] [--dry-run]`
- writes the per-host ssh client block (guide step 7);
behavior in section 10.
- **2.6** `daedalus gpgtools store_publickey
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE | --file PATH)
[--authorized-keys FILE] [--dry-run]` - resolves one SSH
public key and installs it into *this* machine's
authorized_keys (section 11). The source flags are the
send_pubkey set (items 4.1.1-4.1.5), mutually exclusive,
exactly one required.
- **2.7** `daedalus gpgtools initialize [--dry-run]` - checks
that gnupg is ready on this machine and installs what is
missing; the gnupg-only half of initialize_yubikey
(section 12).
## 3. initialize_yubikey behavior
- **3.1** Step 1 - gnupg: `gpg --version`. When it fails, the
package manager is detected (`shutil.which` over apt-get, dnf,
pacman) and gnupg installed via `sudo`; no known manager is
exit 3. A failed install is exit 2.
- **3.1** Step 1 - gnupg: the section 12 flow (item 12.1). When
`gpg --version` fails, the package manager is detected
(`shutil.which` over apt-get, dnf, pacman) and gnupg installed
via `sudo`; no known manager is exit 3. A failed install is
exit 2.
- **3.2** Step 2 - card: `gpg --card-status` parsed for the
`Application type`/`OpenPGP` markers; absent card (including
gpg error text) is exit 4 with the pcscd hint
@@ -101,6 +124,13 @@ Items are cited as `gpgtools spec item N.M`.
All exhausted is exit 8 naming the stores.
- **4.1.4** `--pubkey`: the literal line, validated by item 4.2;
exit 8 when invalid.
- **4.1.5** `--file PATH`: a file holding the SSH public key
line - typically `yubikey_auth.pub` carried on a USB stick
(zero network, zero gpg). Every line is validated per item
4.2: no valid line is exit 8; several valid lines refuse
listing them with the `--pubkey` hint (item 4.1.1
precedent) rather than guessing; an unreadable or missing
file is exit 8.
- **4.2** Key line validation: `ssh-(ed25519|rsa|dss|ecdsa-sha2-*)
<base64> [comment]`, full line; anything else is rejected.
- **4.3** Key material (type + base64, comment ignored) is the
@@ -128,20 +158,26 @@ Items are cited as `gpgtools spec item N.M`.
credentials (agent, passphrase-less key, or ControlMaster
socket). First contact to a brand-new server by password is out
of scope - gain access once manually, then send the key.
- **4.8** Output (identical in section 11): both resolve-and-store
subcommands print the resolved key line, its source, and the
SHA-256 hex digest of the key material (item 4.3) before
acting, so the resolved value can be compared with the machine
the key came from (or read over a phone).
## 5. Exit codes
| Code | Meaning |
| --- | --- |
| 0 | success (initialize ready; send appended or already present) |
| 2 | package install failed (initialize) |
| 3 | gpg missing and no known package manager (initialize) |
| 2 | package install failed (initialize, initialize_yubikey) |
| 3 | gpg missing and no known package manager (initialize, initialize_yubikey) |
| 4 | no OpenPGP card found (initialize) |
| 5 | public-key fetch did not pair the keyring (initialize) |
| 6 | keyring unpaired and the card carries no URL (initialize) |
| 7 | ssh to the target failed; nothing stored (send) |
| 8 | no source resolved a usable key (send) |
| 8 | no source resolved a usable key (send, store); pubkey file missing (configure) |
| 10 | proof-of-possession verification failed; nothing sent (send) |
| 11 | an unmanaged `Host <alias>` exists in the config (configure) |
## 6. Runner contract and injectability
@@ -169,6 +205,10 @@ Items are cited as `gpgtools spec item N.M`.
workspace) are created under the system temp dir and removed in
`finally`. The only persistent write is the target's
`authorized_keys` append via ssh (item 4.6).
- **7.3** store: the local `authorized_keys` (item 11.5) is the
only persistent write; its parent gets mode 700, the file 600.
Scratch rules of item 7.2 apply when remote sources resolve
(item 4.5).
## 8. Testing approach
@@ -180,10 +220,13 @@ Items are cited as `gpgtools spec item N.M`.
no URL, no auth subkey, unpaired), config merge (empty,
preserving, complete), manager mapping and detection,
GNUPGHOME resolution, the initialize flow's success, failure,
warning, and persistence branches, the four sources including
the store chain and fingerprint mismatch, challenge
sign/verify success and refusal, send idempotence by material,
and the CLI wiring, guards, and dry runs.
warning, and persistence branches and the standalone
readiness/install/re-check branches (section 12), the five
sources including the store chain and fingerprint mismatch,
challenge sign/verify success and refusal, send idempotence by
material, store: file sources, append, preservation,
idempotence, perms, dry run, and the CLI wiring, guards, and
dry runs.
- **8.3** The change order is spec item 6.12: this spec first,
then failing tests, then the smallest implementation.
@@ -194,4 +237,105 @@ Items are cited as `gpgtools spec item N.M`.
(steps 1-13; automation notes in section 13).
- **9.2** Repository rules: SPEC items 6.6 (tests), 6.9
(argcomplete opt-in after the parser), 9.8 (version bump).
- **9.3** History: `CHANGELOG.md` entries 0.5.0 and 0.6.0.
- **9.3** History: `CHANGELOG.md` entries 0.5.0, 0.6.0
(initialize/send), 0.7.0 (configure_ssh), 0.8.0
(--file source, store_publickey), 0.9.0 (initialize).
## 10. configure_ssh behavior
- **10.1** The block is written into `--config` (default
`~/.ssh/config`) between managed markers, one block per alias:
```text
# BEGIN daedalus gpgtools: <alias>
Host <alias>
HostName <hostname>
User <user> (omitted without --user)
IdentityFile <pubkey>
IdentityFile <fallback> (omitted per item 10.4)
IdentitiesOnly yes
# END daedalus gpgtools: <alias>
```
- **10.2** Defaults: `--hostname` defaults to the alias itself;
`--pubkey` defaults to `~/.ssh/yubikey_auth.pub`;
`--fallback` defaults to `~/.ssh/id_ed25519`.
- **10.3** Idempotence: a run that finds the alias's markers
replaces the whole marked block with the newly built one;
everything outside the markers is preserved byte-for-byte.
Running twice with the same arguments changes nothing.
- **10.4** The fallback `IdentityFile` is included only when its
file exists and `--no-fallback` was not given; a missing
explicit `--fallback FILE` logs a warning.
- **10.5** Guards: a `--pubkey` file that does not exist is exit
8 with the derive hint; a `Host` line naming the same alias
anywhere outside the managed markers is exit 11 (ssh would let
the first match shadow the managed block).
- **10.6** File hygiene: `~/.ssh` is created at mode 700 when
missing; the config file is created at mode 600 when missing.
- **10.7** `--dry-run` prints the block plus
`creating`/`replacing`, and writes nothing.
## 11. store_publickey behavior
- **11.1** Installs one SSH public key into the *current user's*
`~/.ssh/authorized_keys` (`--authorized-keys FILE` overrides)
on this machine - the machine the key will later grant access
to. Use case: a server with ssh password authentication
disabled that no key authorizes yet; you are logged in at its
console and install the key from inside, so the machine
holding the YubiKey can ssh in afterwards. It is the mirror of
section 4: send pushes the key from where it is, store pulls
it from where the access is.
- **11.2** Sources: identical to items 4.1.1-4.1.5, one per run.
On a bare server the realistic ones are `--pubkey` (typed at
the console), `--file` (USB stick; needs no network and no
gpg), and `--fingerprint` (store chain, needs gpg and
network); `--yubikey` works when the card is plugged into
this machine. An unresolvable source is exit 8 (item 5).
- **11.3** There is no proof-of-possession step (item 4.4) and
no `--no-verify` flag: the private half is, by design,
elsewhere - this machine is the one being granted access, so
nothing here could sign the challenge. Hardening instead: line
validation (item 4.2), fingerprint-checked stores (item
4.1.3), and the identity block (item 11.4).
- **11.4** Identity block: the resolved key line, its source,
and the SHA-256 hex digest of the key material (item 4.3) are
printed before writing (shared rule, item 4.8), so the value
can be compared with the machine the key came from.
- **11.5** Storage: the parent directory is created at mode 700
when missing and the authorized_keys file forced to mode 600,
on every write. Existing entries are preserved verbatim -
authorized_keys is a multi-key file; there is no mismatch
guard on the rest, only the new key's absence is checked.
- **11.6** Idempotence follows item 4.3: the line is appended
only when its material is absent (comments ignored); already
present is reported and exits 0. A missing trailing newline
in an existing file is repaired, never glued into a key line.
- **11.7** `--dry-run` prints the identity block plus
`already present`/`creating` and writes nothing.
- **11.8** No ssh is run and the only persistent write is item
11.5; remote sources keep item 4.5's throwaway-home rule
(item 7.3). Exit codes: 0 stored or already present, 8 no
source resolved a usable key.
## 12. initialize behavior
- **12.1** `initialize` covers the gnupg half of item 3.1
only - no card, keyring, or agent expectations. `gpg
--version` decides readiness: present prints the version
line and exits 0. Missing runs manager detection and the
`sudo` install (item 3.1's manager map); no known manager is
exit 3, a failed install is exit 2. After a successful
install the check re-runs once - still unusable is exit 2.
- **12.2** `--dry-run` performs only the read-only
`gpg --version`, prints what would happen (`already ready`
with the version line, the install command it would run, or
the install-manually message), installs nothing, and exits 0
in every dry-run case.
- **12.3** `initialize_yubikey` runs this flow as its step 1
(item 3.1); a `-2`/`-3` return stops it before anything else.
- **12.4** Intended use: the on-site companion to
store_publickey (item 11) - on a machine without the
YubiKey, run `initialize` first when a gpg-dependent source
(`--fingerprint`, `--url`, `--yubikey`) is wanted.