Withhold secret-looking variables from the processes the runner starts

Workers and the other processes the runner starts copied its whole
environment, tokens and passwords included. ChildProcess::Start now
leaves out every variable whose name contains, in any case, TOKEN,
SECRET, PASSWORD, PASSWD, CREDENTIAL, API_KEY, APIKEY, PRIVATE_KEY or
ACCESS_KEY (IsSecretVariable), unless ChildOptions::keptEnvironment
names it; names compare without case on Windows.

--pass-env=NAME, repeatable, and "pass-env" in catch3.json keep a
variable for the tests. The runner itself still starts with the whole
environment, so code that runs before the first worker sees it;
docs/progmasoft-runner.md says so.

A runner test starts the shell's environment listing with a secret and
a plain variable set, sees only the plain one, and sees the secret once
it is kept.

2 files changed, 13 insertions, 1 deletions

diff --git a/docs/command-line.md b/docs/command-line.md
index 4bd46f3b..236128e1 100644
--- a/docs/command-line.md
+++ b/docs/command-line.md
@@ -71,6 +71,7 @@ Without a spec, every test runs except hidden ones, whose tags start with
 | `-j`, `--jobs=N` | worker processes; 0, the default, uses one per hardware thread |
 | `--in-process` | run the tests in this process, one after another |
 | `--isolate` | start a fresh process for every test |
+| `--pass-env=NAME` | give the tests the variable `NAME`, which they do not get because its name looks like a secret (repeatable) |
 | `--timeout=SECONDS` | the limit for a test without history, and the cap of learned limits; 0 for none |
 | `--no-adaptive-timeout` | use `--timeout` for every test |
 | `--retries=N\|auto\|off` | `auto` (default) retries what may pass again; N retries every failure up to N times |
diff --git a/docs/progmasoft-runner.md b/docs/progmasoft-runner.md
index 8134ae18..19d1e06d 100644
--- a/docs/progmasoft-runner.md
+++ b/docs/progmasoft-runner.md
@@ -274,6 +274,17 @@ accident. `Progmasoft::Catch3::TestTemporaryDirectory()` in
 The directory is removed when the attempt passes and kept when it fails;
 the report says where.
 
+## Environment variables
+
+Workers, and the processes the runner starts for itself, inherit its
+environment without the variables whose names look like secrets: those that
+contain, in any case, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL`,
+`API_KEY`, `APIKEY`, `PRIVATE_KEY` or `ACCESS_KEY`. A test that needs one
+gets it with `--pass-env=NAME`, which can be repeated, or `"pass-env"` in
+the project configuration. The runner itself starts with the whole
+environment, so code that runs before the first worker starts still sees
+them.
+
 
 ## What a failure report says
 
@@ -376,7 +387,7 @@ as on the command line, with the key named in the message:
 | a whole number or a string | `retries` (`"auto"`, `"off"`), `seed` (`"random"`) |
 | a number | `timeout` (seconds), `benchmark-confidence-interval` |
 | a path, relative to the file | `junit`, `json`, `trace`, `shard-durations`; `history`, or `false` for none |
-| an array of strings | `tests` (test specs), `warn` |
+| an array of strings | `tests` (test specs), `warn`, `pass-env` |
 | `"quiet"`, `"normal"` or `"verbose"` | `verbosity` |
 
 `"version": 1` is required; `"$schema"` may name a schema for editors.