docs: per-script local specs + spec-first change order (SPEC 6.11, 6.12)

Every script gets a complete spec.md sectionized like SPEC.md
(python/src/<name>/spec.md, <name>.spec.md for shell scripts).
Change order becomes spec -> tests -> code. Specs added for
gpgtools, hello, hello_bash; CHANGELOG under Unreleased.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 00:54:03 +01:00
parent fef68a84c9
commit 85e8342a74
5 changed files with 308 additions and 5 deletions
+197
View File
@@ -0,0 +1,197 @@
# gpgtools specification
Complete description of `python/src/gpgtools/gpgtools.py`. Change
this file first, then tests, then code (SPEC items 6.11 and 6.12).
Items are cited as `gpgtools spec item N.M`.
<!-- toc-start: headings 2..6 -->
- [1. Purpose](#1-purpose)
- [2. Commands](#2-commands)
- [3. initialize_yubikey behavior](#3-initialize_yubikey-behavior)
- [4. send_pubkey behavior](#4-send_pubkey-behavior)
- [5. Exit codes](#5-exit-codes)
- [6. Runner contract and injectability](#6-runner-contract-and-injectability)
- [7. Files written](#7-files-written)
- [8. Testing approach](#8-testing-approach)
- [9. References](#9-references)
<!-- toc-end -->
## 1. Purpose
- **1.1** gpgtools automates the YubiKey SSH flow documented in the
owner's wiki guide
(`~/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.
- **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
owner into pinentry, never passed through this script.
- **1.3** The user's real GNUPGHOME is written only where section
7 says so; remote public-key imports go to a throwaway home
(item 4.5).
- **1.4** Standard library only; Python 3.11+ (SPEC item 9.6).
## 2. Commands
- **2.1** `daedalus gpgtools` with no subcommand prints the
overview of both 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)
[--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
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.
## 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.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
`systemctl enable --now pcscd`.
- **3.3** Card fields: serial (`Serial number`), authentication
subkey presence (`Authentication key` with a non-`[none]`
value), key URL (`URL of public key`, `[not set]` is None),
keyring pairing (`General key info` non-`[none]`).
- **3.4** Step 3 - public key: when unpaired and a URL exists,
`gpg --fetch-keys <url>`, then re-parse the card; still
unpaired is exit 5. Unpaired without a URL is exit 6 with the
manual-import hint.
- **3.5** A missing `[A]` subkey logs a warning (SSH via
gpg-agent will not work; GPG signing/decryption will) but is
not an error.
- **3.6** Step 4 - agent: the homedir is created at mode 700;
`gpg-agent.conf` gains `enable-ssh-support` and, only when its
key is absent, `default-cache-ttl 600` and `max-cache-ttl
7200`; existing lines, including user TTLs, are kept verbatim
and never duplicated. `gpgconf --kill gpg-agent` restarts the
agent. Exit 0.
## 4. send_pubkey behavior
- **4.1** Sources (exactly one per run):
- **4.1.1** `--yubikey`: the gpg ssh socket from
`gpgconf --list-dirs agent-ssh-socket` (bare path or prefixed
form), `SSH_AUTH_SOCK` set to it, `ssh-add -L`. No socket is
exit 8 with the `initialize_yubikey` hint; no keys is exit 8
with "is the YubiKey plugged in?"; several keys refuses with
the list and the `--pubkey` hint rather than guessing.
- **4.1.2** `--url`: fetch the armored OpenPGP public key,
convert via item 4.5.
- **4.1.3** `--fingerprint`: normalize (strip spaces and `0x`,
case-insensitive, exactly 40 hex chars, else exit 8); resolve
through the store chain, first hit wins: local keyring (`gpg
--export-ssh-key 0x<FP>`), then keys.openpgp.org VKS
(`.../vks/v1/by-fingerprint/<FP>`), then keyserver.ubuntu.com
(`.../pks/lookup?op=get&search=0x<FP>`). Every store result is
fingerprint-checked before use; a mismatch skips the store.
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.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
key's identity for deduplication and reporting.
- **4.4** Proof of possession (default, skipped only with
`--no-verify`): a random hex challenge is signed via
`ssh-keygen -Y sign -U` (the private half - card, PIN prompt
included - must sign) and verified via `ssh-keygen -Y verify`
against the candidate line with an allowed_signers file. Any
failure prints that nothing was sent and exits 10; the ssh
target is never contacted.
- **4.5** Remote conversion: armored keys are imported into a
throwaway `--homedir` via `gpg --import`, fingerprints listed
with `--list-keys --with-colons`, and the ssh line exported with
`gpg --export-ssh-key 0x<FP>`. The real keyring is not touched;
the throwaway home is removed afterwards.
- **4.6** Send: `ssh you@server "cat ~/.ssh/authorized_keys
2>/dev/null"` to read, then - only when the key material is
absent - append the line via stdin with perms forced
(`mkdir -p`, `chmod 700 ~/.ssh`, `chmod 600 authorized_keys`).
Present is reported, not re-appended. Any ssh failure is exit 7;
nothing is appended on failure.
- **4.7** Both ssh calls run without an interactive terminal: the
target must be reachable with existing non-interactive
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.
## 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) |
| 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) |
| 10 | proof-of-possession verification failed; nothing sent (send) |
## 6. Runner contract and injectability
- **6.1** Everything external goes through
`run_command(cmd, input_text="", env=None) -> (code,
stdout+stderr)`: env variables are merged over `os.environ`,
`input_text` is piped to stdin, a missing binary returns
`(127, "<cmd>: not found")`.
- **6.2** `initialize_yukikey(home, run_cmd)`,
`verify_possession(line, workdir, run_cmd)`,
`send_key(line, target, run_cmd)`, and the `source_*`
functions accept the runner; `source_url`,
`source_fingerprint`, and `cmd_send_pubkey` also accept a
`fetch(url) -> bytes | None`. Tests inject fakes; defaults are
`run_command` and `fetch_bytes` (urllib, 30 s timeout, None on
any fetch error).
- **6.3** ssh-keygen signature namespaces and identity are the
constants `daedalus-gpgtools` and `daedalus@verify`.
## 7. Files written
- **7.1** initialize: `<gnupg-home>/gpg-agent.conf` (merge per
item 3.6); the homedir permissions set to 700. Nothing else.
- **7.2** send: scratch dirs (throwaway GNUPGHOME, challenge
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).
## 8. Testing approach
- **8.1** Tests live in `python/tests/test_gpgtools.py` and never
need hardware, a network, or an interactive terminal (SPEC item
6.6): all flows take an injected runner; fetchers and runners
are fakes scripted per test by command prefix.
- **8.2** Covered groups: card-status parsing (present/absent,
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.
- **8.3** The change order is spec item 6.12: this spec first,
then failing tests, then the smallest implementation.
## 9. References
- **9.1** The wiki guide behind items 1.1:
`~/repositories/vibe-wiki/wiki/queries/yubikey-ssh-guide.md`
(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.