README checked against the tree by running every example (closes #22)

Every example in the README was run as written with the published test mnemonic and behaved as the README says, so no sentence changed. The only edit removes the landed work from the TODO section, which now lists the two open owner decisions.

Disclosures:
- `ssh install` and `ssh to` were run by the implementer against a throwaway local `sshd`; the reviewer could not repeat that run and checked those sections by reading the code.
- The child mnemonic vector is reachable only through the test suite and was confirmed there.

Model: opus-4-8 (implementation, review); fable-5-1 (merge message)

.golangci.yml

@@ -16,6 +16,7 @@ linters:
     - depguard         # Dependency allow/block lists
     - godot            # Requires comments to end with periods
     - wsl              # Deprecated, replaced by wsl_v5
+    - gomodguard       # Deprecated, replaced by gomodguard_v2
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
   settings:

README.md

@@ -1,16 +1,74 @@
 # keyfunc
 
-`keyfunc` turns a BIP-39 mnemonic into key pairs that can be recreated from
+`keyfunc` is a Go command-line tool by [@sneak](https://sneak.berlin) — its
-that mnemonic at any time. The same mnemonic, key type and index always give the
+license is not yet chosen
-same key.
+([#14](https://git.eeqj.de/sneak/keyfunc/issues/14)) — that turns a BIP-39
+mnemonic into SSH keys, age identities and child mnemonics, each of which can be
+recreated from that mnemonic at any time. The same mnemonic, key type and index
+always give the same key.
 
 It uses the BIP-85 entropy deriver from `git.eeqj.de/sneak/secret/pkg/bip85` and
 takes the same steps as that repository's `agehd` package.
 
-Commands are grouped by what is derived: `keyfunc ssh ...` for ed25519 SSH
+Commands are grouped by what is derived: `keyfunc ssh ...` for ed25519 SSH keys,
-keys, `keyfunc age ...` for age identities and for encrypting and decrypting
+`keyfunc age ...` for age identities and for encrypting and decrypting with
-with them, and `keyfunc mnemonic ...` for child mnemonics derived from the
+them, and `keyfunc mnemonic ...` for child mnemonics derived from the main one.
-main one.
+
+## Getting Started
+
+Build from a clone and run the binary:
+
+```
+git clone git@git.eeqj.de:sneak/keyfunc.git
+cd keyfunc
+make build
+./keyfunc --version
+```
+
+`make build` produces `./keyfunc`. Every deriving command needs a mnemonic; see
+[Giving it the mnemonic](#giving-it-the-mnemonic) for where it is read from, then
+for example:
+
+```
+./keyfunc ssh pub -n 0 --mnemonic-command 'secret get foo'
+```
+
+## Rationale
+
+A key you can derive again never has to be backed up. One mnemonic, kept safe
+once, stands behind every key this tool produces: lose a laptop and the SSH key,
+the age identity and any child mnemonic on it come back from the mnemonic alone,
+at the same index, byte for byte. Nothing else has to be written down, copied
+between machines, or stored in a secret manager, because it can always be
+derived again.
+
+## Design
+
+The entry point is a thin `cmd/keyfunc/main.go` (what `make build` builds) that
+calls into `internal/`. The packages there are:
+
+- `internal/derive` turns a mnemonic into the 32 bytes a key is made from: it
+  walks BIP-39 seed, BIP-32 master key and BIP-85 entropy, and holds the shared
+  constants (the byte count and the largest key index).
+- `internal/mnemonic` finds the mnemonic to work from — a command, an
+  environment variable, or a terminal prompt — and refuses one that fails the
+  BIP-39 checksum.
+- `internal/sshkey` turns the derived bytes into an ed25519 SSH key
+  (`sshkey.go`) and serves that key from an in-process SSH agent on a private
+  unix socket, keeping it out of any file (`agent.go`).
+- `internal/agekey` turns the derived bytes into an age identity and encrypts
+  and decrypts with it.
+- `internal/childmnemonic` derives a child mnemonic from the main one using
+  BIP-85's own mnemonic application.
+- `internal/cli` builds the cobra command tree and runs it. Under it,
+  `cli/options` holds the flags every command shares, and `cli/ssh`, `cli/age`
+  and `cli/mnemonic` are the command groups.
+
+### Adding a key type
+
+Adding a key type is one package under `internal/` that turns the 32 derived
+bytes into that type's key, plus one cobra subcommand under `internal/cli/` that
+groups its commands.
 
 ## Derivation
 
@@ -54,8 +112,14 @@ If none of these is available and standard input is not a terminal, the tool
 refuses and exits with status 1. A mnemonic that fails the BIP-39 checksum is
 refused with a message saying so.
 
+`KEYFUNC_MNEMONIC` and `KEYFUNC_MNEMONIC_COMMAND` are removed from the
+environment before the system `ssh` (`keyfunc ssh to`) and `sftp`
+(`keyfunc ssh install`) are started, so the mnemonic is never handed on to
+them.
+
 Every command takes `--index` / `-n` and `--mnemonic-command`, and has `--help`.
-`keyfunc --version` prints the version set at build time.
+`keyfunc --version` prints the version. `make build` stamps it; a binary
+installed with `go install` reports the module version instead.
 
 ## SSH keys: `keyfunc ssh`
 
@@ -140,7 +204,9 @@ Derives the key, serves it from an SSH agent that runs inside the tool on a unix
 socket in a new private `0700` temporary directory, then runs the system `ssh`
 with `-o IdentityAgent=<that socket>` followed by the host and all remaining
 arguments unchanged. The tool exits with `ssh`'s exit status and removes the
-socket and directory on the way out. The private key is never written to disk.
+socket and directory on the way out. The private key is never written to disk. A
+SIGINT, SIGTERM or SIGHUP ends `ssh` and still removes the socket and directory,
+and the tool then exits with status 1 unless `ssh` reported one of its own.
 
 ## age identities: `keyfunc age`
 
@@ -150,6 +216,15 @@ the same steps `sneak/secret` takes in its `agehd` package. `secret` derives at
 a vendor-specific path today; for its keys to equal this tool's it moves to
 this path, which is a change in `secret`, not here.
 
+Test vectors, mnemonic
+`abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about`:
+
+```
+recipient index 0: age1xwdy9y6ckyfsgjc8k02e9uhsf3fmjy0ufysewlj68kmx5n67e3nsg2mftq
+recipient index 1: age1pmm92sxaf5mazjwvjph7dx2zq9r5p8l3rarfgqm7hmakqhvgyy4q5p3w7j
+identity index 0: AGE-SECRET-KEY-19QKK2P38598XLXMQFFU3P7J9PLDD7527T70JDHGDJ7AMNF3XT44S00JFU5
+```
+
 ### `keyfunc age pub`
 
 Prints the recipient, the `age1...` public key, on one line.
@@ -182,33 +257,64 @@ not through step 4). Default 12 words. A child mnemonic is a full mnemonic in
 its own right: it can seed another `keyfunc`, another wallet, or `secret`, and
 it never has to be written down, since it can be derived again.
 
-## Adding a key type
+Test vector: the child-mnemonic step is checked against BIP-85's own published
+vectors, which derive from the specification's master key
+`xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb`.
+At key index 0 the 12-word English child mnemonic is:
 
-Adding a key type is one package under `internal/` that turns the 32 derived
+```
-bytes into that type's key, plus one cobra subcommand under `internal/cli/` that
+girl mad pet galaxy egg matter matrix prison refuse sense ordinary nose
-groups its commands.
+```
 
 ## Errors
 
 Errors go to standard error and the exit status is 1, except for `ssh to`,
 which passes through `ssh`'s own exit status.
 
-## Building and running
+## Entrypoints
 
-```
+The repo adheres to the
-make build    # produces ./keyfunc
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
-make check    # fmt-check, lint (golangci-lint) and tests
+standard: most Makefile targets are thin shims over an executable in
-```
+`script/` (`build` and `clean` are the exceptions).
 
-Examples:
+- `script/bootstrap` installs everything needed to build and develop (git, make,
+  Go), idempotently, from nix, apt, brew or apk; it does not install the linter,
+  which only runs inside Docker.
+- `script/setup` prepares a fresh clone: it runs `bootstrap`, then installs the
+  git pre-commit hook.
+- `script/projectname` prints the project name; other scripts call it so they
+  stay identical across repos.
+- `script/test` runs `go vet` and then the test suite, rerunning verbosely if a
+  test fails.
+- `script/lint` runs the linter inside the image built from `Dockerfile.lint`
+  (which pins the linter by hash), so a complaint fails the build and leaves no
+  container behind.
+- `script/fmt` formats the Go source in place.
+- `script/fmt-check` checks that formatting without writing, failing if anything
+  is unformatted.
+- `script/check` runs `test`, `lint` and `fmt-check` and changes no files.
+- `script/docker` builds the Docker image tagged with the project name.
+- `script/cibuild` is the CI build the Gitea workflow calls: it runs the linter,
+  then `docker build`.
+- `script/precommit` is what the git pre-commit hook runs: `go mod tidy` and
+  `go fmt`, failing if `go.mod` or `go.sum` changed, then `check`.
+- `script/install-precommit` installs the git pre-commit hook that runs
+  `script/precommit`.
 
-```
+## TODO
-keyfunc ssh pub -n 3 --mnemonic-command 'secret get foo'
+
-keyfunc ssh priv -n 3 > ~/.ssh/id_bip85_3
+The open issues that stand between the tree and a 1.0 release:
-keyfunc ssh install -n 3 user@example.com
+
-keyfunc ssh to -n 3 user@example.com uptime
+- [#14 Choose a license and add LICENSE](https://git.eeqj.de/sneak/keyfunc/issues/14)
-keyfunc age pub -n 0
+- [#15 Decide the Go module path before 1.0](https://git.eeqj.de/sneak/keyfunc/issues/15)
-keyfunc age encrypt -n 0 --armor -o notes.age notes.txt
+
-keyfunc age decrypt -n 0 notes.age
+## License
-keyfunc mnemonic -n 1 --words 24
+
-```
+Not yet chosen. The license is the owner's decision, still open on the tracker
+([#14](https://git.eeqj.de/sneak/keyfunc/issues/14)); the `LICENSE` file is added
+when that issue is answered.
+
+## Author
+
+[@sneak](https://sneak.berlin).

internal/cli/cli.go

@@ -2,9 +2,13 @@
 package cli
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"os"
+	"os/signal"
+	"runtime/debug"
+	"syscall"
 
 	"git.eeqj.de/sneak/keyfunc/internal/cli/age"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/mnemonic"
@@ -13,20 +17,43 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// Version is what --version prints. The build sets it.
+// devVersion is what Version holds until a build stamps a real one.
+const devVersion = "dev"
+
+// Version is what --version prints. make build stamps it with -ldflags.
 //
 //nolint:gochecknoglobals // set at build time with -ldflags
-var Version = "dev"
+var Version = devVersion
+
+// resolveVersion chooses what --version reports. A value stamped at
+// build time wins. Otherwise, for a binary from go install, the module
+// version recorded in the build info is used, unless that is empty or
+// the "(devel)" of a local build. When neither names a version, the
+// "dev" fallback stays.
+func resolveVersion(stamped string, info *debug.BuildInfo) string {
+	if stamped != devVersion {
+		return stamped
+	}
+
+	if info != nil && info.Main.Version != "" &&
+		info.Main.Version != "(devel)" {
+		return info.Main.Version
+	}
+
+	return devVersion
+}
 
 // Root returns the whole command tree.
 func Root() *cobra.Command {
+	info, _ := debug.ReadBuildInfo()
+
 	root := &cobra.Command{
 		Use:   "keyfunc",
 		Short: "derive key pairs from a BIP-39 mnemonic",
 		Long: "keyfunc turns a BIP-39 mnemonic into key pairs that can " +
 			"be recreated from that mnemonic at any time. The same " +
 			"mnemonic, key type and index always give the same key.",
-		Version:       Version,
+		Version:       resolveVersion(Version, info),
 		SilenceUsage:  true,
 		SilenceErrors: true,
 	}
@@ -42,8 +69,19 @@ func Root() *cobra.Command {
 // status of its own, which "ssh to" uses to hand on the status ssh
 // ended with. ssh has already said whatever it had to say in that
 // case, so nothing more is printed.
+//
+// SIGINT, SIGTERM and SIGHUP cancel the command's context instead of
+// killing the process outright, so the child ssh or sftp ends and the
+// deferred cleanup that removes the agent socket and the install
+// working directory still runs.
 func Main() int {
-	err := Root().Execute()
+	ctx, stop := signal.NotifyContext(
+		context.Background(),
+		syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP,
+	)
+	defer stop()
+
+	err := Root().ExecuteContext(ctx)
 	if err == nil {
 		return 0
 	}

internal/cli/ssh/install.go

@@ -166,6 +166,7 @@ func session(
 
 	//nolint:gosec // the options are the user's own, meant for sftp
 	command := exec.CommandContext(cmd.Context(), "sftp", argv...)
+	command.Env = childEnv()
 	command.Stdin = strings.NewReader(strings.Join(batch, "\n") + "\n")
 	command.Stdout = &said
 	command.Stderr = &said

internal/cli/ssh/ssh.go

@@ -3,9 +3,12 @@ package ssh
 
 import (
 	"fmt"
+	"os"
+	"strings"
 
 	"git.eeqj.de/sneak/keyfunc/internal/cli/options"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
+	"git.eeqj.de/sneak/keyfunc/internal/mnemonic"
 	"git.eeqj.de/sneak/keyfunc/internal/sshkey"
 	"github.com/spf13/cobra"
 )
@@ -84,6 +87,26 @@ func write(cmd *cobra.Command, text string) error {
 	return nil
 }
 
+// childEnv is the tool's environment with the mnemonic variables taken
+// out, for the ssh and sftp children it starts. "ssh to" exists so the
+// private key never leaves the tool; the mnemonic, from either variable,
+// must not leave it either.
+func childEnv() []string {
+	environ := os.Environ()
+	kept := make([]string, 0, len(environ))
+
+	for _, entry := range environ {
+		name, _, _ := strings.Cut(entry, "=")
+		if name == mnemonic.Variable || name == mnemonic.CommandVariable {
+			continue
+		}
+
+		kept = append(kept, entry)
+	}
+
+	return kept
+}
+
 // addComment gives a command its comment flag.
 func addComment(cmd *cobra.Command) {
 	cmd.Flags().String(

internal/cli/ssh/to.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"os/exec"
 	"slices"
+	"syscall"
 
 	"github.com/spf13/cobra"
 )
@@ -70,10 +71,18 @@ func to() *cobra.Command {
 func connect(ctx context.Context, argv []string) error {
 	//nolint:gosec // the arguments are the user's own, meant for ssh
 	command := exec.CommandContext(ctx, "ssh", argv...)
+	command.Env = childEnv()
 	command.Stdin = os.Stdin
 	command.Stdout = os.Stdout
 	command.Stderr = os.Stderr
 
+	// A cancelled context means a signal ended the tool. Send ssh a
+	// SIGTERM rather than the default kill, so it puts the terminal
+	// back the way it found it before it goes.
+	command.Cancel = func() error {
+		return command.Process.Signal(syscall.SIGTERM)
+	}
+
 	err := command.Run()
 	if err == nil {
 		return nil

internal/cli/ssh_test.go

@@ -3,11 +3,14 @@ package cli_test
 import (
 	"bytes"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"slices"
 	"strconv"
 	"strings"
+	"syscall"
 	"testing"
+	"time"
 
 	"git.eeqj.de/sneak/keyfunc/internal/cli"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/ssh"
@@ -15,6 +18,23 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// runAsTool, set in the environment of a re-executed test binary, tells
+// TestMain to run the tool through Main rather than the suite, so the
+// signal test can drive the real signal path in a process it can send a
+// signal to.
+const runAsTool = "KEYFUNC_TEST_RUN_AS_TOOL"
+
+// TestMain re-executes the test binary as the tool when runAsTool is
+// set, and otherwise runs the suite. The signal test starts the tool
+// this way, as a subprocess it can signal and watch clean up.
+func TestMain(m *testing.M) {
+	if os.Getenv(runAsTool) == "1" {
+		os.Exit(cli.Main())
+	}
+
+	os.Exit(m.Run())
+}
+
 // The modes the host is supposed to end up with, and the mode the
 // stand-ins need so that they can be run at all.
 const (
@@ -47,6 +67,9 @@ const (
 	keptIn    = "authorized_keys"
 )
 
+// remoteCommand is the command the "to" tests hand ssh after the host.
+const remoteCommand = "uptime"
+
 // The tool's own name, as it stands in the arguments a test hands to
 // Main, the ssh subcommand both commands the tests here drive live
 // under, and the one of those two these tests name most.
@@ -60,13 +83,19 @@ const (
 // an authorized_keys file.
 const keyLine = vectorZero + " keyfunc/ssh/0\n"
 
+// marker is a variable set beside the mnemonic ones and expected to
+// reach the stand-in, so a scrubbed environment is told apart from an
+// empty one.
+const marker = "KEYFUNC_TEST_MARKER"
+
 // installer is a stand-in for the system sftp for the install
 // command. It writes down the arguments and every command of the
-// batch it is given, echoes each command as sftp does, and carries
+// batch it is given, echoes each command as sftp does, writes down its
-// the commands out against a directory standing in for the host's
+// own environment when a test asks for it, and carries the commands out
-// home directory, so that what keyfunc sends can be watched doing its
+// against a directory standing in for the host's home directory, so that
-// work. A command that begins with a dash may fail; any other failure
+// what keyfunc sends can be watched doing its work. A command that
-// ends the session, as it does in sftp's own batch mode.
+// begins with a dash may fail; any other failure ends the session, as it
+// does in sftp's own batch mode.
 //
 // The listing and the two ways a get can fail are worded as the
 // OpenSSH client words them, each naming the path the server expanded.
@@ -81,6 +110,7 @@ const keyLine = vectorZero + " keyfunc/ssh/0\n"
 // draws the warning ssh writes for it, which carries the wording of a
 // missing file into a session that goes on to authenticate.
 const installer = `
+[ -n "$KEYFUNC_TEST_ENVIRONMENT" ] && env > "$KEYFUNC_TEST_ENVIRONMENT"
 previous=
 for argument in "$@"; do
 	printf '%s\n' "$argument" >> "$KEYFUNC_TEST_ARGUMENTS"
@@ -144,9 +174,11 @@ done
 
 // caller is a stand-in for the system ssh for the to command. It
 // writes down the arguments it was given, notes the agent socket if
-// there really is one at the path it was handed, and ends with the
+// there really is one at the path it was handed, writes down its own
-// status the test asked for.
+// environment when a test asks for it, and ends with the status the
+// test asked for.
 const caller = `
+[ -n "$KEYFUNC_TEST_ENVIRONMENT" ] && env > "$KEYFUNC_TEST_ENVIRONMENT"
 for argument in "$@"; do
 	printf '%s\n' "$argument" >> "$KEYFUNC_TEST_ARGUMENTS"
 done
@@ -157,6 +189,18 @@ fi
 exit "$KEYFUNC_TEST_STATUS"
 `
 
+// sleeper is a stand-in for the system ssh that notes the agent socket
+// and then blocks, so a test can cancel the context while it is running
+// and watch the tool take the agent down. The wait ends on its own only
+// as a backstop, well after the test has cancelled and looked.
+const sleeper = `
+socket=${2#IdentityAgent=}
+if [ -S "$socket" ]; then
+	printf '%s\n' "$socket" > "$KEYFUNC_TEST_SOCKET"
+fi
+sleep 5
+`
+
 // pretended is where a stand-in writes down what it was asked to do.
 type pretended struct {
 	// home stands in for the home directory on the host.
@@ -412,7 +456,7 @@ func TestSSHIsPointedAtTheAgentAndItsStatusIsHandedOn(t *testing.T) {
 
 	arguments, noted := pretendCall(t)
 
-	_, err := execute(t, subcommand, "to", host, "uptime")
+	_, err := execute(t, subcommand, "to", host, remoteCommand)
 
 	var passed ssh.StatusError
 
@@ -421,7 +465,7 @@ func TestSSHIsPointedAtTheAgentAndItsStatusIsHandedOn(t *testing.T) {
 
 	given := recorded(t, arguments)
 	require.Equal(t, "-o", given[0])
-	require.Equal(t, []string{host, "uptime"}, given[2:])
+	require.Equal(t, []string{host, remoteCommand}, given[2:])
 
 	// The stand-in wrote the path down only because there really was
 	// a socket there while it ran.
@@ -439,11 +483,130 @@ func TestTheToolEndsWithTheStatusSSHEndedWith(t *testing.T) {
 
 	t.Cleanup(func() { os.Args = given })
 
-	os.Args = []string{tool, subcommand, "to", host, "uptime"}
+	os.Args = []string{tool, subcommand, "to", host, remoteCommand}
 
 	require.Equal(t, failingStatus, cli.Main())
 }
 
+func TestASignalTakesTheAgentDirectoryDown(t *testing.T) {
+	t.Setenv(mnemonic.Variable, example())
+
+	// The three signals the tool handles, checked one after another.
+	signals := []struct {
+		name   string
+		signal os.Signal
+	}{
+		{"SIGTERM", syscall.SIGTERM},
+		{"SIGINT", syscall.SIGINT},
+		{"SIGHUP", syscall.SIGHUP},
+	}
+
+	for _, ending := range signals {
+		signalEndsTheTool(t, ending.name, ending.signal)
+	}
+}
+
+// signalEndsTheTool runs the tool as a subprocess against a stand-in
+// ssh that blocks, waits until the agent is up and ssh is running
+// against it, sends the tool the signal, and requires the agent socket
+// and its directory to be gone once the tool has ended. The subprocess
+// goes through Main and its signal handling, so with that handling
+// removed the signal kills the tool outright, no deferred cleanup runs,
+// the directory is left behind, and the check fails.
+func signalEndsTheTool(t *testing.T, name string, signal os.Signal) {
+	t.Helper()
+
+	noted := filepath.Join(t.TempDir(), "socket")
+	t.Setenv("KEYFUNC_TEST_SOCKET", noted)
+	standIn(t, "ssh", sleeper)
+
+	//nolint:gosec // the binary is this test's own, re-run as the tool
+	command := exec.CommandContext(
+		t.Context(), os.Args[0], subcommand, "to", host, remoteCommand,
+	)
+
+	command.Env = append(os.Environ(), runAsTool+"=1")
+	require.NoError(t, command.Start())
+
+	// The stand-in notes the socket only once the agent is up and ssh
+	// is running against it, so this is where the signal lands.
+	socket := waitForSocket(t, noted)
+
+	require.NoError(t, command.Process.Signal(signal))
+	waitForTool(t, name, command)
+
+	// The signal ended the tool, and its deferred cleanup still ran:
+	// the agent socket and its directory are gone.
+	require.NoDirExists(t, filepath.Dir(socket), name)
+}
+
+// waitForTool waits for the subprocess to end, and fails the test if it
+// does not end in time.
+func waitForTool(t *testing.T, name string, command *exec.Cmd) {
+	t.Helper()
+
+	done := make(chan error, 1)
+	go func() { done <- command.Wait() }()
+
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatalf("the tool did not end after %s", name)
+	}
+}
+
+// waitForSocket waits for the stand-in to write down the agent socket
+// and gives back the path, which means the agent is up and ssh is
+// running against it.
+func waitForSocket(t *testing.T, noted string) string {
+	t.Helper()
+
+	var socket string
+
+	require.Eventually(t, func() bool {
+		content, err := os.ReadFile(noted) //nolint:gosec // test path
+		if err != nil {
+			return false
+		}
+
+		socket = strings.TrimSpace(string(content))
+
+		return socket != ""
+	}, 5*time.Second, 5*time.Millisecond)
+
+	return socket
+}
+
+func TestTheMnemonicIsNotHandedToSFTP(t *testing.T) {
+	t.Setenv(mnemonic.CommandVariable, "echo "+example())
+	t.Setenv(mnemonic.Variable, example())
+	t.Setenv(marker, "reaches the stand-in")
+
+	pretendHost(t)
+	environment := recordEnvironment(t)
+
+	install(t, host)
+
+	mnemonicWithheld(t, read(t, environment))
+}
+
+func TestTheMnemonicIsNotHandedToSSH(t *testing.T) {
+	t.Setenv(mnemonic.CommandVariable, "echo "+example())
+	t.Setenv(mnemonic.Variable, example())
+	t.Setenv(marker, "reaches the stand-in")
+
+	pretendCall(t)
+	environment := recordEnvironment(t)
+
+	_, err := execute(t, subcommand, "to", host, remoteCommand)
+
+	var passed ssh.StatusError
+
+	require.ErrorAs(t, err, &passed)
+
+	mnemonicWithheld(t, read(t, environment))
+}
+
 // pretendHost puts the install stand-in on the path and gives back the
 // places it writes to.
 func pretendHost(t *testing.T) pretended {
@@ -592,6 +755,28 @@ func standIn(t *testing.T, name, body string) {
 	)
 }
 
+// recordEnvironment asks the stand-in to write its environment down and
+// gives back the file it writes it to.
+func recordEnvironment(t *testing.T) string {
+	t.Helper()
+
+	path := filepath.Join(t.TempDir(), "environment")
+	t.Setenv("KEYFUNC_TEST_ENVIRONMENT", path)
+
+	return path
+}
+
+// mnemonicWithheld requires that neither mnemonic variable reached the
+// stand-in and that the marker set beside them did, so an empty
+// environment does not pass for a scrubbed one.
+func mnemonicWithheld(t *testing.T, environment string) {
+	t.Helper()
+
+	require.NotContains(t, environment, mnemonic.Variable+"=")
+	require.NotContains(t, environment, mnemonic.CommandVariable+"=")
+	require.Contains(t, environment, marker+"=")
+}
+
 // read returns what is in a file.
 func read(t *testing.T, path string) string {
 	t.Helper()

internal/cli/version_internal_test.go

@@ -0,0 +1,37 @@
+package cli
+
+import (
+	"runtime/debug"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestResolveVersion(t *testing.T) {
+	t.Parallel()
+
+	release := &debug.BuildInfo{Main: debug.Module{Version: "v1.2.3"}}
+	local := &debug.BuildInfo{Main: debug.Module{Version: "(devel)"}}
+	empty := &debug.BuildInfo{}
+
+	t.Run("stamped value wins over build info", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, "v0.1.0", resolveVersion("v0.1.0", release))
+	})
+
+	t.Run("go install reports the module version", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, "v1.2.3", resolveVersion(devVersion, release))
+	})
+
+	t.Run("a local build stays dev", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, devVersion, resolveVersion(devVersion, local))
+	})
+
+	t.Run("no version anywhere stays dev", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, devVersion, resolveVersion(devVersion, empty))
+		require.Equal(t, devVersion, resolveVersion(devVersion, nil))
+	})
+}