# swarm-secret-client

Reading and writing a swarm credential in the secret store, over `vaultrs`.
The HTTP is that crate's job. What this one owns is the **agreements** both
ends of the store have to state identically: where a credential lives, which
field its bytes are in, and how this deployment's environment becomes a
logged-in client.

The surrounding picture — which secret is minted where, and why delivery is a
copy rather than a bind mount — is [`docs/swarm/secrets.md`](../docs/swarm/secrets.md).

## Why a crate and not a module per binary

The store has two Rust ends and they are peers: the swarm controller writes a
credential, a hive reads it. Neither is senior to the other, so a path
formatted at each call site is an agreement with no owner — it holds right up
until one side is edited alone, and then it fails as a missing key rather than
as a mismatch.

The third end is what settles it. `nix/host-modules/glue-matrix-bao-token.nix`
reads the store with `bao kv get -field=value`. That reader is a shell line in
a nix module: it cannot be renamed by the same refactor as a Rust struct, and
no Rust test reaches it. So the field name is pinned by a test against the
serialised literal rather than left to the struct definition.

## The identity is a certificate, and the role is the hive's name

Authentication is the store's `cert` auth method.
`nix/host-modules/glue-bao-tls.nix` mints the client certificate with its CN
set to the hive's name, because a cert-auth role matches on the CN. So
`cert_role` is not a free choice for the caller: a hive passes its own name,
and the policy attached to that role is what scopes what it may read.

The listener's `tls_require_and_verify_client_cert` is a different thing and
not a substitute. It decides who may open a connection; it says nothing about
who the connection belongs to, and a store with the option set and no `cert`
mount configured refuses every login made here. That refusal is what
`Error::Vault` out of `connect` means.

## Configuration

`Settings::from_env` reads `BAO_ADDR`, `BAO_CLIENT_CERT`, `BAO_CLIENT_KEY`,
and the optional `BAO_CACERT`.

**The `BAO_` spellings are read explicitly rather than left to `vaultrs`.** Its
own defaults look for `VAULT_ADDR` / `VAULT_CLIENT_CERT` / `VAULT_CLIENT_KEY`,
which no unit in this tree sets. Falling through to them builds a client with
**no identity at all**, and that surfaces as a TLS handshake failure — a place
that names neither the variable nor the reason.

**Empty is as absent as unset.** systemd renders an unset nix option as
`Environment=BAO_CACERT=`, so empty is the shape a missing value arrives in.

**The certificate and key are paths, not values**, and are read at connect
time — same rule as every other credential in this tree, for the same reason:
a value in a nix expression is rendered into the world-readable store.

Reading the environment is separate from connecting (`Settings::from_lookup`)
because every one of those failures is a misconfiguration an operator has to
read an error about, and none of them needs a reachable store to happen.

## Names that arrive from elsewhere

`path::matrix_account` is fallible, which for a string formatter needs saying:
its segments are an agent name from the topology and an account name from that
agent's own config. A `/` turns one agent's segment into another agent's
directory and `..` walks out of the prefix entirely, so the charset it accepts
is deliberately narrower than what the store would.

## What this crate does not do

It has no opinion on **what** a caller may read. That is the policy attached to
the cert role, and it lives in the store.

It holds the token minted at login and renews nothing. A handle is built per
credential, so the login is the cheap part of a rare operation — a caller that
wanted to keep one alive across a token's lifetime would need more than this.