From 791b136012183c6e06482366000e44d3250780c3 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:02:54 +0200 Subject: [PATCH] test: contract tests for how callers use nodkey run Fixes #198 Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 4 + DESIGN.md | 11 + docs/setup.md | 17 + test/contract/README.md | 75 ++++ test/contract/contract_linux_test.go | 293 ++++++++++++ test/contract/harness_linux_test.go | 644 +++++++++++++++++++++++++++ test/contract/helper_linux_test.go | 184 ++++++++ 7 files changed, 1228 insertions(+) create mode 100644 test/contract/README.md create mode 100644 test/contract/contract_linux_test.go create mode 100644 test/contract/harness_linux_test.go create mode 100644 test/contract/helper_linux_test.go diff --git a/AGENTS.md b/AGENTS.md index bc42dca..82f6475 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,6 +93,10 @@ Planned. Each v1 issue adds its part. - `tools/prgate/` - the behavior-change gate that the PR title workflow runs from `main` (docs/releasing.md, "Changes in behavior for callers"). `.github/pull_request_template.md` has its line. +- `test/contract/` - the contract tests (DESIGN.md section 17): what a + caller of `nodkey run` sees. A change to one of them is a change in + behavior for callers; see `test/contract/README.md`. Only that README + and `*_test.go` files go in this folder. - `.claude/agents/security-reviewer.md` - the security review every change gets. diff --git a/DESIGN.md b/DESIGN.md index c5e2e0b..a381f85 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -4552,6 +4552,17 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`): something to find: the broker handed out the secret (a `secret_sent` entry), and SSH logins went through the wrapper. So a `-run` filter that leaves out the cases makes the search fail, not pass. +- **Contract tests** (`test/contract`, #198): what a program or a + script that calls `nodkey run` sees, as section 5 ("What the command + gets") documents it. They run the built `nodkey` against a trial broker + (`nodkey try`), with stdout and stderr on pipes and on a + pseudo-terminal, masked and with `execve`: the password command, the + parent of the command, exit codes and signals, stdin and inherited file + descriptors, and a deny (exit 77, the command never runs). The command + reports only facts and a SHA-256 of the value, never the value. They + run in the `go test -race ./...` job of every pull request. A change to + one of them is a change in behavior for callers (section 18, + `test/contract/README.md`). - **One manual test with a real Telegram bot**, written down in [docs/manual-telegram-test.md](docs/manual-telegram-test.md). The token comes from a local file and is never committed. It ran on 2026-10-15, diff --git a/docs/setup.md b/docs/setup.md index 81c6ec4..63924ce 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2240,6 +2240,23 @@ itself stops, its last line on stderr is expired, 69 when the broker cannot be reached, 64 for wrong usage ([DESIGN.md section 15](../DESIGN.md#15-commands-and-exit-codes)). +Tests pin each of these patterns, with stdout and stderr on pipes and on +a terminal, masked and with `--no-mask`. They are in +[test/contract](../test/contract/README.md), in +`contract_linux_test.go`. A change to one of them is a change in +behavior for callers: + +| pattern | test | +|---|---| +| a password command that prints the secret gets `***` | `TestPasswordCommandThroughPipeGetsMask` | +| the program runs inside `nodkey run` and reads its own environment | `TestPasswordCommandInsideRunGetsValue` | +| the parent of the command, and `/proc/PID/stat` and `/proc/PID/exe` of nodkey | `TestParentProcess` | +| the exit code of the command | `TestExitCode` | +| a command that dies of a signal | `TestDeathBySignal` | +| `SIGTERM` and `SIGHUP` reach the command | `TestSignalsReachCommand` | +| stdin, fd 3, and what stdout and stderr of the command are | `TestStdinAndFileDescriptors` | +| a denied request: exit 77, and the command does not run | `TestDenied` | + ### SSH: nodkey ssh-agent `nodkey ssh-agent` is an SSH agent without keys. For each login, it asks diff --git a/test/contract/README.md b/test/contract/README.md new file mode 100644 index 0000000..3658a8a --- /dev/null +++ b/test/contract/README.md @@ -0,0 +1,75 @@ +# Contract tests + +These tests pin what a program or a script sees when it calls +`nodkey run`. They test the behavior that callers rely on, not the code +inside nodkey. They came after #191: the change to masking in #171 passed +every unit test, but it broke two kinds of callers. + +**A change to a file here is a change in behavior for callers.** A pull +request that changes, removes or moves a file here, also the harness or +the helper, must say `Changes behavior for existing callers: yes`, must +put `!` in its title, and must add a section to +[docs/updating.md](../../docs/updating.md). The PR check does this +([docs/releasing.md](../../docs/releasing.md#changes-in-behavior-for-callers)). +Only two things do not count: a new `*_test.go` file, because a new +test pins behavior that callers already have, and a change to this +README. So put a new test in a new file. + +Only this README and `*_test.go` files go in this folder: no subfolder, +no `testdata/`, no `go.mod`. The check counts any other new file as a +change in behavior. + +## How they work + +- `TestMain` builds `./cmd/nodkey` and starts a trial broker with + `nodkey try` in a private directory. The tests answer its requests on + its stdin: "Approve N min" for `demo-token`, and Deny for every other + request. They run the real `nodkey run` with the client config of the + trial. +- The command is the test binary itself (the helper), or `/bin/sh`. The + helper writes facts to a report file: its process IDs, the name of its + parent, what its stdin and fd 3 held, and the SHA-256 of the secret in + its environment. It never writes the value, and no test prints it, also + not on a failure. +- Each test runs in the ways that apply to it, out of five (pattern 5): + stdout and stderr on pipes; + stdout on a pipe and stderr on a pseudo-terminal; both on a + pseudo-terminal with `--mask`; both on a pseudo-terminal (`execve`); + and pipes with `--no-mask` (`execve`). +- They need Linux, `/bin/sh` and `/dev/ptmx`, and no root. They run in + the `go test -race ./...` job of CI. + +## The patterns + +The documented behavior is in DESIGN.md section 5 ("What the command +gets") and in docs/setup.md section 11 ("Keep the mask on: password +commands and wrappers"). + +1. A password command: a program reads the output of `nodkey run` through + a pipe, and gets `***`: `TestPasswordCommandThroughPipeGetsMask`. The + documented way, where the program runs inside `nodkey run` and its + password command reads the program's own environment, gets the value: + `TestPasswordCommandInsideRunGetsValue`. +2. The parent of the command. Masked: a process named `nodkey`, whose + parent is the caller; its `/proc/PID/stat` can be read and its + `/proc/PID/exe` cannot (as root, that one check is left out). With + `execve`: the command has the process ID of `nodkey run`, and its + parent is the caller: `TestParentProcess`. +3. Exit codes and signals. The exit code of the command: + `TestExitCode`. A command that dies of a signal: `TestDeathBySignal`. + `SIGTERM` and `SIGHUP` reach the command; masked, `SIGINT` and + `SIGUSR1` do not; with `execve`, they do: `TestSignalsReachCommand`. +4. stdin and inherited file descriptors: the command reads the stdin of + `nodkey run`, and fd 3 that the caller passed reaches it. Masked, its + stdout and stderr are pipes: `TestStdinAndFileDescriptors`. +5. Each test above, on pipes and on a pseudo-terminal (see "How they + work"). + +Also: a denied request ends with exit 77, and the command does not run: +`TestDenied`. + +## Run them + +```sh +go test -race ./test/contract/... +``` diff --git a/test/contract/contract_linux_test.go b/test/contract/contract_linux_test.go new file mode 100644 index 0000000..f6be2bf --- /dev/null +++ b/test/contract/contract_linux_test.go @@ -0,0 +1,293 @@ +package contract + +// The contract tests: each pins one pattern of a caller of nodkey run, as +// DESIGN.md section 5 ("What the command gets") and docs/setup.md section +// 11 ("Keep the mask on") document it. A change to a test here is a +// change in behavior for callers (README.md). + +import ( + "os" + "os/signal" + "slices" + "strings" + "syscall" + "testing" + "time" +) + +// secretHash returns the SHA-256 of the value of approvedSecret, as the +// command sees it in its environment. It never holds the value itself. +func secretHash(t *testing.T) string { + t.Helper() + r := run(t, call{mode: modes[0], helper: helperFacts}) + r.wantExit(0) + f := r.facts() + if f.EnvHash == "" || !f.EnvTry { + t.Fatalf("the command did not get a value of nodkey try in %s", secretVar) + } + return f.EnvHash +} + +// Pattern 1: a program reads the secret through a pipe from a password +// command. With the mask, it gets ***; this run never gets the value. +func TestPasswordCommandThroughPipeGetsMask(t *testing.T) { + for _, m := range modes { + if !m.masked || m.out == terminals { + continue // stdout is not a pipe, or the value is not masked + } + t.Run(m.name, func(t *testing.T) { + r := run(t, call{mode: m, argv: []string{"printenv", secretVar}}) + r.wantExit(0) + // Never print the output, not even its length: it could be + // the value. + if r.stdout.String() != "***\n" { + t.Error("the program did not read only \"***\\n\" through the pipe") + } + }) + } +} + +// Pattern 1, the documented way: the program runs inside nodkey run, and +// its password command reads the program's own environment. It gets the +// value, on a pipe and on a terminal. +func TestPasswordCommandInsideRunGetsValue(t *testing.T) { + want := secretHash(t) + for _, m := range modes { + t.Run(m.name, func(t *testing.T) { + r := run(t, call{mode: m, helper: helperProgram}) + r.wantExit(0) + var got *event + for _, e := range r.events() { + if e.Event == "program" { + got = &e + } + } + switch { + case got == nil: + t.Fatal("the program did not run") + case got.Error != "": + t.Fatal(got.Error) + case got.Hash == hashOf([]byte("***")): + t.Error("the password command got *** in place of the value") + case got.Hash != want: + t.Error("the password command got another value than the secret") + } + }) + } +} + +// Pattern 2: the parent of the command. Masked: a process named nodkey, +// not dumpable, whose parent is the caller, in the same process group and +// session. execve: the command has the process ID of nodkey run, and its +// parent is the caller. +func TestParentProcess(t *testing.T) { + for _, m := range modes { + t.Run(m.name, func(t *testing.T) { + r := run(t, call{mode: m, helper: helperFacts}) + r.wantExit(0) + f := r.facts() + nodkeyPID, caller := r.cmd.Process.Pid, os.Getpid() + if !m.masked { + if f.PID != nodkeyPID { + t.Errorf("execve: the command has process ID %d; want %d, the one of nodkey run", f.PID, nodkeyPID) + } + if f.PPID != caller { + t.Errorf("execve: the parent of the command is %d; want the caller %d", f.PPID, caller) + } + return + } + if f.PPID != nodkeyPID { + t.Errorf("masked: the parent of the command is %d; want nodkey run, %d", f.PPID, nodkeyPID) + } + if f.ParentStatErr != "" { + t.Fatalf("masked: /proc/PID/stat of nodkey cannot be read: %s", f.ParentStatErr) + } + if f.ParentName != "nodkey" { + t.Errorf("masked: the parent is named %q in /proc/PID/stat; want \"nodkey\"", f.ParentName) + } + if f.ParentPPID != caller { + t.Errorf("masked: the parent of nodkey is %d; want the caller %d", f.ParentPPID, caller) + } + if f.Pgrp != f.ParentPgrp || f.Session != f.ParentSession { + t.Errorf("masked: the command is in process group %d, session %d; nodkey in %d, %d", + f.Pgrp, f.Session, f.ParentPgrp, f.ParentSession) + } + if os.Geteuid() == 0 { + t.Log("the test runs as root: root can read /proc/PID/exe of nodkey, so that check is left out") + } else if f.ParentExe != "EACCES" { + t.Errorf("masked: readlink /proc/PID/exe of nodkey gave %q; want EACCES (nodkey is not dumpable)", f.ParentExe) + } + }) + } +} + +// Pattern 3: the exit code of the command is the exit code of nodkey run. +func TestExitCode(t *testing.T) { + for _, m := range modes { + t.Run(m.name, func(t *testing.T) { + r := run(t, call{mode: m, argv: []string{"/bin/sh", "-c", "exit 42"}}) + r.wantExit(42) + }) + } +} + +// Pattern 3: when the command dies of a signal. Masked: nodkey dies of +// the same signal for SIGTERM, SIGHUP, SIGINT and SIGKILL, and exits with +// 128 and the number for another one. execve: the command is nodkey run, +// so the caller sees its signal. +func TestDeathBySignal(t *testing.T) { + for _, m := range modes { + for _, sig := range []syscall.Signal{syscall.SIGTERM, syscall.SIGHUP, syscall.SIGINT, syscall.SIGKILL, syscall.SIGUSR1} { + t.Run(m.name+"/"+sig.String(), func(t *testing.T) { + // An ignored signal stays ignored in the children, so + // the shell cannot die of it. + needSignals(t, sig) + name := strings.TrimPrefix(signalName(sig), "SIG") + r := run(t, call{mode: m, argv: []string{"/bin/sh", "-c", "kill -s " + name + " $$"}}) + if m.masked && sig == syscall.SIGUSR1 { + r.wantExit(128 + int(sig)) + return + } + r.wantSignal(sig) + }) + } + } +} + +func signalName(sig syscall.Signal) string { + switch sig { + case syscall.SIGTERM: + return "TERM" + case syscall.SIGHUP: + return "HUP" + case syscall.SIGINT: + return "INT" + case syscall.SIGKILL: + return "KILL" + case syscall.SIGUSR1: + return "USR1" + } + return "" +} + +// Pattern 3: SIGTERM and SIGHUP to nodkey run reach the command. Masked: +// nodkey does not pass SIGINT or SIGUSR1 on. execve: every signal goes to +// the command. +func TestSignalsReachCommand(t *testing.T) { + for _, m := range modes { + for _, sig := range []syscall.Signal{syscall.SIGTERM, syscall.SIGHUP} { + t.Run(m.name+"/"+sig.String(), func(t *testing.T) { + // nodkey does not catch a signal that it got ignored + // (DESIGN.md section 5), so it would not pass it on. + needSignals(t, syscall.SIGINT, syscall.SIGUSR1, sig) + r := start(t, call{mode: m, helper: helperSignals}) + r.waitEvent("ready from the command", func(e event) bool { return e.Event == "ready" }) + pid := r.cmd.Process.Pid + var want []string + for _, other := range []syscall.Signal{syscall.SIGINT, syscall.SIGUSR1} { + if err := syscall.Kill(pid, other); err != nil { + t.Fatal(err) + } + if !m.masked { + // execve: wait until the command got it, so the + // order of the signals is known. + n := signalName(other) + r.waitEvent("signal "+n+" at the command", func(e event) bool { return e.Event == "signal" && e.Signal == n }) + want = append(want, n) + } + } + if m.masked { + // A check that something does not come needs time. + // Without it, a SIGINT that nodkey passes on could + // still be on its way when the command exits on sig + // (Linux delivers SIGHUP before SIGINT), and the test + // would pass. nodkey passes a signal on at once, so + // half a second is plenty. + time.Sleep(500 * time.Millisecond) + } + if err := syscall.Kill(pid, sig); err != nil { + t.Fatal(err) + } + r.wait() + r.wantExit(100 + int(sig)) + want = append(want, signalName(sig)) + if got := r.signals(); !slices.Equal(got, want) { + t.Errorf("the command got the signals %q; want %q", got, want) + } + }) + } + } +} + +// Pattern 4: the command reads the stdin of nodkey run, and a file +// descriptor that the caller passed to nodkey run (fd 3) reaches it. +// Masked, stdout and stderr of the command are pipes (to nodkey); with +// execve, they are those of the caller. +func TestStdinAndFileDescriptors(t *testing.T) { + const stdin, fd3 = "data on stdin\n", "data on fd 3\n" + for _, m := range modes { + t.Run(m.name, func(t *testing.T) { + r := run(t, call{mode: m, helper: helperFacts, stdin: []byte(stdin), fd3: []byte(fd3)}) + r.wantExit(0) + f := r.facts() + if f.Stdin != stdin { + t.Errorf("the command read %q on stdin; want %q", f.Stdin, stdin) + } + if f.FD3 != fd3 { + t.Errorf("the command read %q on fd 3; want %q", f.FD3, fd3) + } + wantOut, wantErr := "pipe", "pipe" + if !m.masked && m.out == terminals { + wantOut, wantErr = "terminal", "terminal" + } + if f.Stdout != wantOut || f.Stderr != wantErr { + t.Errorf("stdout and stderr of the command are %s and %s; want %s and %s", f.Stdout, f.Stderr, wantOut, wantErr) + } + }) + } +} + +// A denied request: nodkey run exits with 77, its last line says so, and +// the command never runs. The first request gets a tap on Deny. After it, +// the broker denies the next requests for the same secret without a +// message, for 60 seconds (DESIGN.md section 8); they end in the same way. +func TestDenied(t *testing.T) { + for _, m := range modes { + t.Run(m.name, func(t *testing.T) { + r := run(t, call{mode: m, secret: deniedSecret, helper: helperFacts}) + r.wantExit(77) + if setup.trial.denied.Load() == 0 { + t.Error("the broker never asked, so the exit code 77 does not come from a tap on Deny") + } + if evs := r.events(); len(evs) > 0 { + t.Errorf("the command ran after a deny: %d events", len(evs)) + } + if m.out == pipes { + if !strings.HasSuffix(r.stderr.String(), " (exit 77)\n") { + // Do not print stderr: keep output of nodkey run out of + // failures. + t.Error("the last line on stderr does not end with \"(exit 77)\"") + } + } else { + r.ptyOut.waitFor(t, " (exit 77)") + } + }) + } +} + +// needSignals stops the test when the test process ignores one of sigs, +// as under nohup: then the children ignore it too, and the test cannot +// check what it should. In CI that is a failure, not a skip, so the check +// is never lost there. +func needSignals(t *testing.T, sigs ...syscall.Signal) { + t.Helper() + for _, sig := range sigs { + if !signal.Ignored(sig) { + continue + } + if os.Getenv("CI") != "" { + t.Fatalf("the test process ignores %v, so this test cannot run; run it without that", sig) + } + t.Skipf("the test process ignores %v, so this test cannot run; run it without that", sig) + } +} diff --git a/test/contract/harness_linux_test.go b/test/contract/harness_linux_test.go new file mode 100644 index 0000000..6766f0a --- /dev/null +++ b/test/contract/harness_linux_test.go @@ -0,0 +1,644 @@ +package contract + +// The harness of the contract tests: it builds nodkey, starts a trial +// broker with "nodkey try", answers its requests, and runs "nodkey run" +// with the test binary itself as the command (the helper, see +// helper_linux_test.go). See README.md. + +import ( + "bufio" + "bytes" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io" + "os" + "os/exec" + "path/filepath" + "runtime" + "strconv" + "strings" + "sync" + "sync/atomic" + "syscall" + "testing" + "time" + "unsafe" +) + +// The environment variables between the test and its helper. nodkey run +// passes its environment on to the command. +const ( + helperVar = "NODKEY_CONTRACT_HELPER" // the mode of the helper + reportVar = "NODKEY_CONTRACT_REPORT" // the file that the helper writes its events to + fd3Var = "NODKEY_CONTRACT_FD3" // "1": the helper reads fd 3 + secretVar = "CONTRACT_SECRET" // the variable of the secret +) + +// The secrets of the trial broker. The harness approves each request for +// approvedSecret for some minutes, and denies every other request. +const ( + approvedSecret = "demo-token" + deniedSecret = "demo-password" +) + +// waitLimit caps each wait of the tests. +const waitLimit = 30 * time.Second + +// setup is what TestMain made. +var setup struct { + nodkey string // the built nodkey binary + home string // HOME of nodkey run: its client config is in it + self string // the test binary, the helper + trial *trial +} + +func TestMain(m *testing.M) { + if mode := os.Getenv(helperVar); mode != "" { + os.Exit(helper(mode)) + } + os.Exit(runTests(m)) +} + +// runTests builds nodkey, starts the trial broker, runs the tests, and +// removes what it made. +func runTests(m *testing.M) int { + stderr := os.Stderr //nolint:forbidigo // TestMain reports on stderr, as the testing package does. + var err error + if setup.self, err = os.Executable(); err != nil { + _, _ = fmt.Fprintln(stderr, "contract: cannot find the test binary:", err) + return 1 + } + build, err := os.MkdirTemp("", "nodkey-contract-") + if err != nil { + _, _ = fmt.Fprintln(stderr, "contract: cannot make a temporary directory:", err) + return 1 + } + defer func() { _ = os.RemoveAll(build) }() + setup.nodkey = filepath.Join(build, "nodkey") + if err := buildNodkey(setup.nodkey); err != nil { + _, _ = fmt.Fprintln(stderr, "contract: cannot build nodkey:", err) + return 1 + } + tr, err := startTrialSomewhere() + setup.trial = tr + if err != nil { + _, _ = fmt.Fprintln(stderr, "contract: cannot start the trial broker (nodkey try):", err) + return 1 + } + code := m.Run() + if err := tr.stop(); err != nil { + _, _ = fmt.Fprintln(stderr, "contract: the trial broker did not stop cleanly:", err) + code = 1 + } + _ = os.RemoveAll(tr.dir) + return code +} + +// startTrialSomewhere starts the trial broker in a new private directory. +// Every directory on the way to its files must pass the file checks of +// nodkey (DESIGN.md section 14), and the system temporary directory fails +// them. So the directory is in XDG_RUNTIME_DIR or in the cache directory +// of the user, as in the tests of cmd/nodkey. +func startTrialSomewhere() (*trial, error) { + var bases []string + if d := os.Getenv("XDG_RUNTIME_DIR"); d != "" { + bases = append(bases, d) + } + if d, err := os.UserCacheDir(); err == nil { + bases = append(bases, d) + } + var errs []error + for _, base := range bases { + if err := os.MkdirAll(base, 0o700); err != nil { //nolint:gosec // G703: a base directory of the user. + errs = append(errs, err) + continue + } + dir, err := os.MkdirTemp(base, "nodkey-contract-") + if err != nil { + errs = append(errs, err) + continue + } + tr, err := startTrial(dir) + if err == nil { + return tr, nil + } + _ = os.RemoveAll(dir) //nolint:gosec // G703: the test's own new directory. + errs = append(errs, fmt.Errorf("in %s: %w", base, err)) + } + return nil, fmt.Errorf("no directory works for it: %w", errors.Join(errs...)) +} + +// buildNodkey builds ./cmd/nodkey of this repository as bin, with the Go +// that built the test. +func buildNodkey(bin string) error { + root, err := filepath.Abs(filepath.Join("..", "..")) + if err != nil { + return err + } + goTool := "go" + //nolint:staticcheck // SA1019: the root of the toolchain that built this test binary is what is wanted here. + if r := runtime.GOROOT(); r != "" { + if p := filepath.Join(r, "bin", "go"); fileExists(p) { + goTool = p + } + } + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute) + defer cancel() + cmd := exec.CommandContext(ctx, goTool, "build", "-o", bin, "./cmd/nodkey") //nolint:gosec // G204: the test builds nodkey with its own arguments. + cmd.Dir = root + if out, err := cmd.CombinedOutput(); err != nil { + return fmt.Errorf("go build: %w\n%s", err, out) + } + return nil +} + +func fileExists(path string) bool { + _, err := os.Stat(path) + return err == nil +} + +// trial is the trial broker: "nodkey try" in a child process. It reads +// the answers on its stdin, and shows each request on its stdout. +type trial struct { + dir string // its files, and the home directory of nodkey run + cmd *exec.Cmd + in io.WriteCloser + ready chan struct{} + done chan struct{} // the answers ended: the stdout of nodkey try is closed + + denied atomic.Int64 // the requests that the harness denied + + mu sync.Mutex + out bytes.Buffer // what nodkey try wrote: names and short codes, no values +} + +// startTrial starts nodkey try with its files in dir, and puts its client +// config into setup.home. +func startTrial(dir string) (*trial, error) { + run := filepath.Join(dir, "run") + setup.home = filepath.Join(dir, "home") + conf := filepath.Join(setup.home, ".config", "nodkey") + for _, d := range []string{run, conf} { + if err := os.MkdirAll(d, 0o700); err != nil { //nolint:gosec // G703: in the test's own new directory. + return nil, err + } + } + tr := &trial{dir: dir, ready: make(chan struct{}), done: make(chan struct{})} + // Not with the context of a test: the trial lives for all of them. + tr.cmd = exec.CommandContext(context.Background(), setup.nodkey, "try") //nolint:gosec // G204: the nodkey binary of the test. + tr.cmd.Env = append(os.Environ(), "XDG_RUNTIME_DIR="+run) + in, err := tr.cmd.StdinPipe() + if err != nil { + return nil, err + } + tr.in = in + out, err := tr.cmd.StdoutPipe() + if err != nil { + return nil, err + } + tr.cmd.Stderr = &lockedWriter{mu: &tr.mu, w: &tr.out} + if err := tr.cmd.Start(); err != nil { + return nil, err + } + go tr.answer(out) + select { + case <-tr.ready: + case <-tr.done: + _ = tr.stop() + return nil, fmt.Errorf("nodkey try stopped; it wrote:\n%s", tr.output()) + case <-time.After(waitLimit): + _ = tr.stop() + return nil, fmt.Errorf("nodkey try is not ready after %s; it wrote:\n%s", waitLimit, tr.output()) + } + b, err := os.ReadFile(filepath.Join(run, "nodkey-try", "client.toml")) //nolint:gosec // G304: the client config of the trial. + if err != nil { + _ = tr.stop() + return nil, err + } + if err := os.WriteFile(filepath.Join(conf, "client.toml"), b, 0o600); err != nil { //nolint:gosec // G703: in the test's own new directory. + _ = tr.stop() + return nil, err + } + return tr, nil +} + +// answer reads the stdout of nodkey try. It answers each request: "Approve +// N min" when it asks only for approvedSecret, else Deny. +func (tr *trial) answer(out io.Reader) { + defer close(tr.done) + sc := bufio.NewScanner(out) + var code, secrets string + for sc.Scan() { + line := sc.Text() + tr.mu.Lock() + tr.out.WriteString(line + "\n") + tr.mu.Unlock() + const prefix = "nodkey try: TRY MODE: " + switch { + case strings.HasPrefix(line, prefix+"a trial broker listens on "): + close(tr.ready) + case strings.HasPrefix(line, prefix+"request ") && strings.Contains(line, " from client "): + code, secrets = strings.Fields(strings.TrimPrefix(line, prefix+"request "))[0], "" + case strings.HasPrefix(line, " secrets: "): + secrets = strings.TrimPrefix(line, " secrets: ") + case strings.HasPrefix(line, " type:") && code != "": + choice := "3" // Deny + if secrets == approvedSecret { + choice = "2" // Approve N min + } else { + tr.denied.Add(1) + } + _, _ = fmt.Fprintf(tr.in, "%s %s\n", code, choice) + code = "" + } + } +} + +func (tr *trial) output() string { + tr.mu.Lock() + defer tr.mu.Unlock() + return tr.out.String() +} + +// stop ends nodkey try with SIGTERM: it removes its files. +func (tr *trial) stop() error { + // No more answers: a request that comes now expires. + _ = tr.in.Close() + _ = tr.cmd.Process.Signal(syscall.SIGTERM) + waited := make(chan error, 1) + go func() { waited <- tr.cmd.Wait() }() + select { + case err := <-waited: + return err + case <-time.After(waitLimit): + _ = tr.cmd.Process.Kill() + return errors.New("nodkey try did not end after SIGTERM") + } +} + +// lockedWriter writes to w under mu. +type lockedWriter struct { + mu *sync.Mutex + w io.Writer +} + +func (l *lockedWriter) Write(p []byte) (int, error) { + l.mu.Lock() + defer l.mu.Unlock() + return l.w.Write(p) +} + +// output is where stdout and stderr of nodkey run go. +type output int + +const ( + pipes output = iota // both pipes + terminals // both one pseudo-terminal + stdoutPipeOnly // stdout a pipe, stderr a pseudo-terminal +) + +// mode is one way to call nodkey run: where its output goes, and its flags. +type mode struct { + name string + out output + flags []string + masked bool // the documented form: masked, or execve +} + +// modes are the ways to call nodkey run that the tests check (pattern 5). +// Masked is the default when stdout or stderr is not a terminal, or with +// --mask; execve when both are a terminal, or with --no-mask. +var modes = []mode{ + {name: "pipe", out: pipes, masked: true}, + {name: "stdout pipe, stderr terminal", out: stdoutPipeOnly, masked: true}, + {name: "terminal --mask", out: terminals, flags: []string{"--mask"}, masked: true}, + {name: "terminal", out: terminals, masked: false}, + {name: "pipe --no-mask", out: pipes, flags: []string{"--no-mask"}, masked: false}, +} + +// call is one nodkey run. +type call struct { + mode mode + secret string // the secret NAME; approvedSecret when empty + helper string // the mode of the helper as the command, or "" + argv []string // the command when helper is "" + stdin []byte // nil: stdin is /dev/null + fd3 []byte // nil: no fd 3 +} + +// running is a nodkey run that has started. +type running struct { + t *testing.T + cmd *exec.Cmd + report string + stdout bytes.Buffer // only when stdout is a pipe + stderr bytes.Buffer // only when stderr is a pipe + pty *os.File // the master side, or nil + ptyOut *ptyReader +} + +// start starts nodkey run for c. The test fails when it cannot. +func start(t *testing.T, c call) *running { + t.Helper() + r := &running{t: t, report: filepath.Join(t.TempDir(), "report")} + secret := c.secret + if secret == "" { + secret = approvedSecret + } + args := append([]string{"run"}, c.mode.flags...) + args = append(args, "--secret", secretVar+"="+secret, "--reason", "contract test", "--") + if c.helper != "" { + args = append(args, setup.self) + } else { + args = append(args, c.argv...) + } + // Not the test's context: a test that ends must not kill nodkey run + // with SIGKILL before it checks how nodkey run ended. + r.cmd = exec.CommandContext(context.Background(), setup.nodkey, args...) //nolint:gosec // G204: the nodkey binary of the test. + // GORACE: a helper built with -race waits a second when it exits, unless + // told not to. + r.cmd.Env = append(os.Environ(), "HOME="+setup.home, helperVar+"="+c.helper, reportVar+"="+r.report, + "GORACE=atexit_sleep_ms=0") + if c.stdin != nil { + r.cmd.Stdin = bytes.NewReader(c.stdin) + } + if c.fd3 != nil { + path := filepath.Join(t.TempDir(), "fd3") + if err := os.WriteFile(path, c.fd3, 0o600); err != nil { + t.Fatal(err) + } + f, err := os.Open(path) //nolint:gosec // G304: a file of the test. + if err != nil { + t.Fatal(err) + } + defer func() { _ = f.Close() }() + r.cmd.ExtraFiles = []*os.File{f} + r.cmd.Env = append(r.cmd.Env, fd3Var+"=1") + } + var pts *os.File + if c.mode.out != pipes { + r.pty, pts = openPty(t) + defer func() { _ = pts.Close() }() + r.ptyOut = readPty(r.pty) + } + switch c.mode.out { + case pipes: + r.cmd.Stdout, r.cmd.Stderr = &r.stdout, &r.stderr + case terminals: + r.cmd.Stdout, r.cmd.Stderr = pts, pts + case stdoutPipeOnly: + r.cmd.Stdout, r.cmd.Stderr = &r.stdout, pts + } + if err := r.cmd.Start(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { + if r.cmd.ProcessState == nil { + _ = r.cmd.Process.Kill() + _ = r.cmd.Wait() + } + if r.pty != nil { + _ = r.pty.Close() + } + }) + return r +} + +// run starts nodkey run for c and waits until it ends. +func run(t *testing.T, c call) *running { + t.Helper() + r := start(t, c) + r.wait() + return r +} + +// wait waits until nodkey run ends. +func (r *running) wait() syscall.WaitStatus { + r.t.Helper() + waited := make(chan error, 1) + go func() { waited <- r.cmd.Wait() }() + select { + case <-waited: + case <-time.After(waitLimit): + _ = r.cmd.Process.Kill() + <-waited + r.t.Fatalf("nodkey run did not end after %s", waitLimit) + } + return r.status() +} + +// status is how nodkey run ended. +func (r *running) status() syscall.WaitStatus { + ws, ok := r.cmd.ProcessState.Sys().(syscall.WaitStatus) + if !ok { + r.t.Fatal("no wait status") + } + return ws +} + +// wantExit checks that nodkey run exited with code. +func (r *running) wantExit(code int) { + r.t.Helper() + ws := r.status() + if !ws.Exited() || ws.ExitStatus() != code { + r.t.Errorf("nodkey run ended with %s; want exit code %d", describe(ws), code) + } +} + +// wantSignal checks that nodkey run died of sig. +func (r *running) wantSignal(sig syscall.Signal) { + r.t.Helper() + ws := r.status() + if !ws.Signaled() || ws.Signal() != sig { + r.t.Errorf("nodkey run ended with %s; want death by signal %d (%v)", describe(ws), int(sig), sig) + } +} + +func describe(ws syscall.WaitStatus) string { + switch { + case ws.Exited(): + return "exit code " + strconv.Itoa(ws.ExitStatus()) + case ws.Signaled(): + return fmt.Sprintf("death by signal %d (%v)", int(ws.Signal()), ws.Signal()) + } + return fmt.Sprintf("wait status %#x", uint32(ws)) +} + +// event is one line that the helper writes to its report. It never holds +// a value: only facts, and a SHA-256 of a value. +type event struct { + Event string `json:"event"` // "facts", "ready", "signal", "program" + Facts *facts `json:"facts,omitempty"` // for "facts" + Signal string `json:"signal,omitempty"` // for "signal": TERM, HUP, INT or USR1 + Hash string `json:"hash,omitempty"` // for "program": the SHA-256 of what the password command printed + Error string `json:"error,omitempty"` // for "program" +} + +// facts is what the command found out about its process. +type facts struct { + PID int `json:"pid"` + PPID int `json:"ppid"` + Pgrp int `json:"pgrp"` + Session int `json:"session"` + ParentName string `json:"parent_name"` // the name in /proc/PPID/stat + ParentStatErr string `json:"parent_stat_err"` // "" when /proc/PPID/stat could be read + ParentPPID int `json:"parent_ppid"` + ParentPgrp int `json:"parent_pgrp"` + ParentSession int `json:"parent_session"` + ParentExe string `json:"parent_exe"` // "ok", "EACCES", or another error of readlink /proc/PPID/exe + EnvHash string `json:"env_hash"` // the SHA-256 of the secret in its environment + EnvTry bool `json:"env_try"` // the value starts with TRY-, as each value of nodkey try + Stdin string `json:"stdin"` + FD3 string `json:"fd3"` + Stdout string `json:"stdout"` // "terminal", "pipe" or "other" + Stderr string `json:"stderr"` +} + +// events reads the report of the helper. A missing report has no events. +func (r *running) events() []event { + r.t.Helper() + b, err := os.ReadFile(r.report) + if errors.Is(err, os.ErrNotExist) { + return nil + } + if err != nil { + r.t.Fatal(err) + } + var evs []event + for _, line := range strings.Split(string(b), "\n") { + if line == "" { + continue + } + var e event + if err := json.Unmarshal([]byte(line), &e); err != nil { + r.t.Fatalf("a line of the report is not JSON: %v", err) + } + evs = append(evs, e) + } + return evs +} + +// waitEvent waits until the report has an event that ok accepts. +func (r *running) waitEvent(what string, ok func(event) bool) { + r.t.Helper() + deadline := time.Now().Add(waitLimit) + for { + for _, e := range r.events() { + if ok(e) { + return + } + } + if r.cmd.ProcessState != nil { + r.t.Fatalf("nodkey run ended before %s", what) + } + if time.Now().After(deadline) { + r.t.Fatalf("no %s after %s", what, waitLimit) + } + time.Sleep(5 * time.Millisecond) + } +} + +// facts returns the facts that the helper reported. +func (r *running) facts() facts { + r.t.Helper() + for _, e := range r.events() { + if e.Event == "facts" && e.Facts != nil { + return *e.Facts + } + } + r.t.Fatal("the command reported no facts: did it run?") + return facts{} +} + +// signals returns the signals that the helper got, in order. +func (r *running) signals() []string { + var s []string + for _, e := range r.events() { + if e.Event == "signal" { + s = append(s, e.Signal) + } + } + return s +} + +// hashOf is the SHA-256 of b, in hex. +func hashOf(b []byte) string { + h := sha256.Sum256(b) + return hex.EncodeToString(h[:]) +} + +// openPty opens a new pseudo-terminal, with no controlling terminal. +func openPty(t *testing.T) (master, slave *os.File) { + t.Helper() + ptmx, err := os.OpenFile("/dev/ptmx", os.O_RDWR|syscall.O_NOCTTY, 0) + if err != nil { + if os.Getenv("CI") != "" { + t.Fatalf("no pseudo-terminal: %v", err) + } + t.Skipf("no pseudo-terminal: %v", err) + } + var unlock int32 + if _, _, e := syscall.Syscall(syscall.SYS_IOCTL, ptmx.Fd(), syscall.TIOCSPTLCK, uintptr(unsafe.Pointer(&unlock))); e != 0 { //nolint:gosec // G103: the ioctl needs the address. + _ = ptmx.Close() + t.Fatalf("unlockpt: %v", e) + } + var n uint32 + if _, _, e := syscall.Syscall(syscall.SYS_IOCTL, ptmx.Fd(), syscall.TIOCGPTN, uintptr(unsafe.Pointer(&n))); e != 0 { //nolint:gosec // G103: the same. + _ = ptmx.Close() + t.Fatalf("ptsname: %v", e) + } + pts, err := os.OpenFile("/dev/pts/"+strconv.FormatUint(uint64(n), 10), os.O_RDWR|syscall.O_NOCTTY, 0) + if err != nil { + _ = ptmx.Close() + t.Fatal(err) + } + return ptmx, pts +} + +// ptyReader reads the master side of a pseudo-terminal, so that writes to +// it never block. +type ptyReader struct { + mu sync.Mutex + buf bytes.Buffer +} + +func readPty(master *os.File) *ptyReader { + p := &ptyReader{} + go func() { + b := make([]byte, 4096) + for { + n, err := master.Read(b) + p.mu.Lock() + if p.buf.Len() < 1<<16 { + p.buf.Write(b[:n]) + } + p.mu.Unlock() + if err != nil { + return + } + } + }() + return p +} + +// waitFor waits until the pseudo-terminal showed text. +func (p *ptyReader) waitFor(t *testing.T, text string) { + t.Helper() + deadline := time.Now().Add(waitLimit) + for { + p.mu.Lock() + found := bytes.Contains(p.buf.Bytes(), []byte(text)) + p.mu.Unlock() + if found { + return + } + if time.Now().After(deadline) { + t.Fatalf("the terminal did not show %q after %s", text, waitLimit) + } + time.Sleep(5 * time.Millisecond) + } +} diff --git a/test/contract/helper_linux_test.go b/test/contract/helper_linux_test.go new file mode 100644 index 0000000..230883d --- /dev/null +++ b/test/contract/helper_linux_test.go @@ -0,0 +1,184 @@ +package contract + +// The helper: the test binary run again as the command of nodkey run. It +// writes what it finds to the report file (event), never a value: only a +// SHA-256 of one. + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "io" + "os" + "os/exec" + "os/signal" + "strconv" + "strings" + "syscall" + "time" + "unsafe" +) + +// The modes of the helper. +const ( + helperFacts = "facts" // report facts, then exit 0 + helperSignals = "signals" // report each signal; exit 100+n on SIGTERM or SIGHUP + helperProgram = "program" // a program with a password command that reads its own environment +) + +// helper runs the helper in mode and returns its exit code. +func helper(mode string) int { + switch mode { + case helperFacts: + return report(event{Event: "facts", Facts: collectFacts()}) + case helperSignals: + return waitSignals() + case helperProgram: + return passwordProgram() + } + return 2 +} + +// report appends e to the report file, as one write. It returns 0, or 3 +// when it cannot. +func report(e event) int { + b, err := json.Marshal(e) + if err != nil { + return 3 + } + f, err := os.OpenFile(os.Getenv(reportVar), os.O_WRONLY|os.O_APPEND|os.O_CREATE, 0o600) //nolint:gosec // G703: the report file that the test named. + if err != nil { + return 3 + } + _, err = f.Write(append(b, '\n')) + if cerr := f.Close(); err == nil { + err = cerr + } + if err != nil { + return 3 + } + return 0 +} + +// collectFacts finds out the facts of this process. +func collectFacts() *facts { + f := &facts{PID: os.Getpid(), PPID: os.Getppid()} + if _, _, pgrp, session, err := readStat("self"); err == nil { + f.Pgrp, f.Session = pgrp, session + } + parent := strconv.Itoa(f.PPID) + name, ppid, pgrp, session, err := readStat(parent) + if err != nil { + f.ParentStatErr = err.Error() + } + f.ParentName, f.ParentPPID, f.ParentPgrp, f.ParentSession = name, ppid, pgrp, session + switch _, err := os.Readlink("/proc/" + parent + "/exe"); { + case err == nil: + f.ParentExe = "ok" + case errors.Is(err, syscall.EACCES): + f.ParentExe = "EACCES" + default: + f.ParentExe = err.Error() + } + if v, ok := os.LookupEnv(secretVar); ok { + h := sha256.Sum256([]byte(v)) + f.EnvHash = hex.EncodeToString(h[:]) + f.EnvTry = strings.HasPrefix(v, "TRY-") + } + if b, err := io.ReadAll(io.LimitReader(os.Stdin, 4096)); err == nil { + f.Stdin = string(b) + } + if os.Getenv(fd3Var) == "1" { + fd3 := os.NewFile(3, "fd3") + if b, err := io.ReadAll(io.LimitReader(fd3, 4096)); err == nil { + f.FD3 = string(b) + } + } + f.Stdout, f.Stderr = kind(1), kind(2) + return f +} + +// readStat reads the name, the parent, the process group and the session +// of a process from /proc/PID/stat. +func readStat(pid string) (name string, ppid, pgrp, session int, err error) { + b, err := os.ReadFile("/proc/" + pid + "/stat") //nolint:gosec // G304: a file of /proc. + if err != nil { + return "", 0, 0, 0, err + } + s := string(b) + open, closing := strings.IndexByte(s, '('), strings.LastIndexByte(s, ')') + if open < 0 || closing < open { + return "", 0, 0, 0, errors.New("no name in /proc/PID/stat") + } + fields := strings.Fields(s[closing+1:]) + if len(fields) < 4 { + return "", 0, 0, 0, errors.New("too few fields in /proc/PID/stat") + } + ppid, _ = strconv.Atoi(fields[1]) + pgrp, _ = strconv.Atoi(fields[2]) + session, _ = strconv.Atoi(fields[3]) + return s[open+1 : closing], ppid, pgrp, session, nil +} + +// kind says what the file descriptor fd is: "terminal", "pipe" or "other". +func kind(fd int) string { + var st syscall.Stat_t + if err := syscall.Fstat(fd, &st); err != nil { + return "closed" + } + if st.Mode&syscall.S_IFMT == syscall.S_IFIFO { + return "pipe" + } + var tio syscall.Termios + if _, _, e := syscall.Syscall(syscall.SYS_IOCTL, uintptr(fd), syscall.TCGETS, uintptr(unsafe.Pointer(&tio))); e == 0 { //nolint:gosec // G103: the ioctl needs the address. + return "terminal" + } + return "other" +} + +// signalNames are the signals that the helper catches. +var signalNames = map[os.Signal]string{ + syscall.SIGTERM: "TERM", syscall.SIGHUP: "HUP", syscall.SIGINT: "INT", syscall.SIGUSR1: "USR1", +} + +// waitSignals reports "ready", then each signal that comes. On SIGTERM or +// SIGHUP it exits with 100 and the number of the signal. +func waitSignals() int { + ch := make(chan os.Signal, 8) + for s := range signalNames { + signal.Notify(ch, s) + } + if code := report(event{Event: "ready"}); code != 0 { + return code + } + timeout := time.After(waitLimit) + for { + select { + case s := <-ch: + if code := report(event{Event: "signal", Signal: signalNames[s]}); code != 0 { + return code + } + if n, ok := s.(syscall.Signal); ok && (n == syscall.SIGTERM || n == syscall.SIGHUP) { + return 100 + int(n) + } + case <-timeout: + return 99 + } + } +} + +// passwordProgram is a program that reads a password from a command +// through a pipe, as a mail client does: the command prints the secret +// from the program's own environment (docs/setup.md, section 11). It +// reports the SHA-256 of what it read. +func passwordProgram() int { + ctx, cancel := context.WithTimeout(context.Background(), waitLimit) + defer cancel() + out, err := exec.CommandContext(ctx, "/bin/sh", "-c", "printenv "+secretVar).Output() + if err != nil { + return report(event{Event: "program", Error: "the password command failed"}) + } + return report(event{Event: "program", Hash: hashOf([]byte(strings.TrimSuffix(string(out), "\n")))}) +}