# M4a task 04: secrets, and the runbook entries for `gatewayd`

**Branch:** `m4a` (run `git switch m4a`; `git status --short` must be empty, otherwise stop)
**Commit subject:** `gatewayd: secrets from a credential, the environment or a file; runbook entries`

## Goal

`gatewayd`'s one secret is the Mattermost token. It can come from three places, chosen per secret
in `gatewayd.toml` (spec section 4, P15 in the brief):

| Form | Reads | Refused when |
|---|---|---|
| `credential = "<name>"` | `$CREDENTIALS_DIRECTORY/<name>`, which systemd fills for a service with `LoadCredentialEncrypted=` | the variable is unset, or the file cannot be read |
| `env = "<VAR>"` | the environment variable | unset, or not UTF-8 |
| `file = "<absolute path>"` | the file | not absolute; a symbolic link; not a regular file; not owned by the user `gatewayd` runs as; any group or other permission bit set |

In every form one trailing newline is removed, and an empty value is refused. A secret read from a
**file** is in plaintext on disk: `gatewayd` still starts, but `load` returns this warning for it,
exactly (`<name>` and `<path>` filled in, `path.display()`):

```text
gatewayd: warning: secret <name> is read in plaintext from <path>; a systemd credential keeps it encrypted at rest (see docs/runbook.md#secret-in-a-file)
```

The value must never reach a log: `Secret` has no `Display`, its `Debug` prints `Secret(…)`, it is
wiped when dropped (`zeroize::Zeroizing`), and `expose()` is the only way to the text.

This task also adds the runbook entries for every fail-closed state of `gatewayd`, all seven at
once, so that later tasks can point at them.

## Files

- Copy: `crates/gatewayd/tests/secrets.rs`, and the skeleton `crates/gatewayd/src/secrets.rs`
- Append: `docs/plans/M4a/files/runbook-gatewayd.md` to the end of `docs/runbook.md`
- Modify: `crates/gatewayd/src/lib.rs` (`pub mod secrets;`), `docs/implementer-log.md`

## The skeleton

Written: `Secret` (with `new`, `expose` and its `Debug`), `Loaded { secret, warning }`,
`SecretError { name, why }` and its `Display` (`secret <name>: <why>` then a newline and
`see docs/runbook.md#secret-unavailable`), and the constants `RUNBOOK` and `RUNBOOK_FILE`. To fill:
`load`, `check_file` and `value`.

`load` takes the environment as a function, `env: &dyn Fn(&str) -> Option<OsString>`, so that tests
can pass their own: read `CREDENTIALS_DIRECTORY` and `env` variables through it, never through
`std::env`. The uid of the user `gatewayd` runs as is the owner of `/proc/self`
(`std::fs::metadata("/proc/self")?.uid()`, from `std::os::unix::fs::MetadataExt`); no `unsafe`, no
`libc`.

The `why` of each error, for the reader: say what is wrong and never the value. The reference used
these, and you may too:

| Case | `why` |
|---|---|
| credential, variable unset | `CREDENTIALS_DIRECTORY is not set: gatewayd was not started by systemd with LoadCredentialEncrypted=` |
| credential, unreadable | `cannot read the credential <path>: <error>` |
| env unset | `the environment variable <VAR> is not set` |
| env not UTF-8 | `the environment variable <VAR> is not UTF-8` |
| file checks | `<path> is not an absolute path`, `cannot read <path>: <error>`, `<path> is a symbolic link`, `<path> is not a regular file`, `<path> is not owned by the user gatewayd runs as`, `<path> has mode <mode as {:03o}>; only the owner may read it (0600 or 0400)` |
| the value | `the value is not UTF-8`, `the value is empty` |

## Steps

- [ ] **1. Copy.** `git switch m4a`, then
  `cp docs/plans/M4a/files/crates/gatewayd/tests/secrets.rs crates/gatewayd/tests/ && cp docs/plans/M4a/files/crates/gatewayd/src/secrets.rs crates/gatewayd/src/`
  and `cat docs/plans/M4a/files/runbook-gatewayd.md >> docs/runbook.md`. Add `pub mod secrets;` to
  `crates/gatewayd/src/lib.rs`.
- [ ] **2. See it fail.** `cargo test -p gatewayd --test secrets`. Expected: it compiles and 8
  tests fail.
- [ ] **3. Fill `value`, then `check_file`, then `load`.** `cargo check -p gatewayd` after each.
- [ ] **4. See it pass.** `cargo test -p gatewayd --test secrets`. Expected: 8 passed.
- [ ] **5. Check the runbook.** `grep -c '^## ' docs/runbook.md` is 7 more than before step 1, and
  `sh scripts/check-runbook.sh` prints nothing and exits 0.
- [ ] **6. Run the gate.** `cargo fmt --all`, then `make gate`. Expected last line: `gate: ok`.
- [ ] **7. Log and commit.**
  `git add crates/gatewayd docs/runbook.md docs/implementer-log.md Cargo.lock && git commit`

## Done when

- `cargo test -p gatewayd --test secrets` passes; the seven entries are in `docs/runbook.md`;
  `make gate` prints `gate: ok`.

## Stop and report if

- A test needs the secret's value in an error message, or `unsafe` looks necessary.