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:
@@ -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.
|
||||
Reference in New Issue
Block a user