Files
daedalus/README.md
T
nvaldez fef68a84c9 feat: gpgtools - YubiKey GPG/SSH helpers (v0.6.0)
initialize_yubikey (guide steps 1-4): gnupg install fallback
(apt-get/dnf/pacman), card check, public-key fetch from the
card's URL field, idempotent gpg-agent SSH config merge,
GNUPGHOME chmod 700; --dry-run, --gnupg-home.

send_pubkey (guide steps 5-6): resolve the SSH public key from
four sources (--yubikey via gpg-agent ssh socket, --url, --fingerprint via store chain local keyring -> keys.openpgp.org
-> keyserver.ubuntu.com with fingerprint checking, --pubkey
literal), prove possession of the private half with a random
challenge signature (ssh-keygen -Y sign -U / verify) before
anything is stored, then append idempotently to the target's
authorized_keys (dedup by key material, comments ignored).
--no-verify opts out explicitly; --dry-run resolves only.

51 tests (flow via injected runner: no hardware, network, or
interactive terminal); steps 1-6 of the wiki guide
(yubikey-ssh-guide.md) are now one command each.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 00:46:40 +01:00

108 lines
4.5 KiB
Markdown

# daedalus (template)
Starter repository for daedalus:
one CLI, many small scripts, each with tests.
```bash
daedalus <name> [args...] # run a script
daedalus <category> [category...] # list scripts in the categories (AND)
daedalus --list # list everything
```
**[Install, usage, and development](./INSTALL.md)** ·
[SPEC](./SPEC.md) (how the repo is maintained) ·
[CHANGELOG](./CHANGELOG.md)
## Available scripts
| 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) |
| `hello` | Python | test | Prints a hello line and the daedalus version |
| `hello_bash` | Bash | test | Sample bash script through the shared help() interface |
Run the sample script:
```bash
daedalus hello # hello from daedalus 0.4.0
daedalus hello_bash me # hello, me (from daedalus bash)
daedalus hello_bash -h # usage from hello_bash's help()
daedalus test hello # same, through the category prefix
daedalus test # list the scripts in the 'test' category
```
`daedalus --list` prints the version, a `script` / `type` / `categories`
table, and each description wrapped under each row.
### gpgtools
`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.
```bash
daedalus gpgtools # overview of the subcommands
daedalus gpgtools initialize_yubikey # prepare this machine
daedalus gpgtools initialize_yubikey --dry-run # print the plan only
```
| Argument | Default | Meaning |
| --- | --- | --- |
| `--dry-run` | off | Print the plan, write nothing |
| `--gnupg-home DIR` | `GNUPGHOME` or `~/.gnupg` | Which GnuPG home to configure |
Exit codes: `0` ready, `2` package install failed, `3` gpg missing and
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
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,
and nothing is sent when verification fails.
```bash
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 --yubikey --dry-run you@server # resolve only
```
| Argument | Default | Meaning |
| --- | --- | --- |
| `--yubikey` | — | Key from the plugged YubiKey via gpg-agent (must be the only agent key) |
| `--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 |
| `--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 |
Additional exit codes: `7` ssh to the target failed, `8` no source
resolved a key, `10` proof-of-possession verification failed (nothing
was sent).
## Shell completion
Bash (and other shells argcomplete supports) completes script names and
category labels: `daedalus hel` + TAB completes `hello`, `daedalus test h` +
TAB completes `hello` inside the category, and options complete after `-`.
See [INSTALL](./INSTALL.md#tab-completion).
## Getting started
1. Clone or copy this template and name the Git remote for your team.
2. Add a script under `python/src/`, `bash/`, `powershell/`, or `batch/`
(see [SPEC layout](./SPEC.md#2-layout)); bash scripts implement the
shared `help()` interface (SPEC item 6.10).
3. Register it in `daedalus/registry.py`, add a row to the table above,
write tests, bump `version` in `pyproject.toml`, and run
`python autotest.py`.
`hello` is the sample script: copy its file, registry entry, README row,
and tests to add your own. Unknown names exit with code 2 and suggest
close matches.