swarmctl: add bao init and bao grant-bootstrap

init prints the store's keys and root token once and keeps none; with
--and-grant it goes on to the granter bootstrap in the same process.
grant-bootstrap does that step alone, reading the root token from a
hidden prompt or stdin. The token reaches bao only as BAO_TOKEN in the
child's environment.

docs/1-getting-started/setup.md

@@ -23,23 +23,36 @@ _On the host running `swarm-bao`._ Everything else fetches its credentials
 from the store, so it comes first.
 
 ```bash
-sudo bao operator init   # keep the keys it prints and the root token OFF this host
+swarmctl bao init
 ```
 
+It prints the unseal (or, under the default `pkcs11` seal, recovery) keys
+and the root token **once**, and stores none of them: not in a file, and the root token is
+never in a process's argument list (so not in `ps`). Record them off this host before you do
+anything else. It refuses an initialised store, and works
+from any host that can reach the store and has `bao` on `PATH`; the
+wrapper installed on the store host already knows the store's address and CA.
+
 Then bootstrap the **granter**, the one principal that writes every
 `swarm-*` policy and role from then on. This is the only step that needs
-the root token:
+the root token. Run it as root on the host running `swarm-bao`:
 
 ```bash
-sudo -i
-read -rs BAO_TOKEN && export BAO_TOKEN          # paste the root token from `bao operator init`
-bao policy write bao-bootstrap /etc/hyperhive/bao-bootstrap-policy.hcl
-bao token create -policy=bao-bootstrap -ttl=24h -orphan -display-name=bao-bootstrap -field=token \
-  | install -D -m 0600 /dev/stdin /var/lib/swarm-bao-bootstrap/grant.token
-unset BAO_TOKEN
-systemctl restart swarm-bao-granter-role
+swarmctl bao grant-bootstrap     # prompts for the root token, input hidden
 ```
 
+It writes the `bao-bootstrap` policy, places a 24h grant token for
+`swarm-bao-granter-role` and restarts that unit. The token comes from the
+hidden prompt, or from stdin when stdin isn't a terminal; never from an
+argument or environment variable. If the granter exists already, it
+says so and does nothing. To do both steps in one go,
+without re-typing the root token, run `swarmctl bao init --and-grant`
+instead (it needs the `pkcs11` seal, which unseals itself).
+
+If the host running `swarm-bao` has no `swarmctl` (the controller runs
+elsewhere), the granting units print the equivalent `bao` commands when the
+store refuses them.
+
 Check `systemctl status swarm-bao-granter-role` logs
 `Uploaded policy: bao-granter`, then restart the granting units that
 failed while they waited. The granter unit deletes the token itself after a

docs/2-handbook/swarm/swarmctl-cli.md

@@ -37,6 +37,9 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl forge make-admin`↴](#swarmctl-forge-make-admin)
 * [`swarmctl setup`↴](#swarmctl-setup)
 * [`swarmctl setup status`↴](#swarmctl-setup-status)
+* [`swarmctl bao`↴](#swarmctl-bao)
+* [`swarmctl bao init`↴](#swarmctl-bao-init)
+* [`swarmctl bao grant-bootstrap`↴](#swarmctl-bao-grant-bootstrap)
 * [`swarmctl login`↴](#swarmctl-login)
 * [`swarmctl completions`↴](#swarmctl-completions)
 
@@ -53,6 +56,7 @@ swarm-level operator CLI
 * `user` — Manage subjects in the swarm's SSO provider
 * `forge` — Manage human accounts on the swarm's forge
 * `setup` — Show where the first-run setup ceremony stands
+* `bao` — Initialise the swarm's secret store and bootstrap its granter
 * `login` — Log in to the swarm named by `--swarm` as your own SSO account
 * `completions` — Generate a shell completion script for `swarmctl` and print it to stdout
 
@@ -671,6 +675,56 @@ Exits 0 when every step it can see has finished, and 1 otherwise, including when
 
 
 
+## `swarmctl bao`
+
+Initialise the swarm's secret store and bootstrap its granter.
+
+Runs the `bao` CLI against the store over HTTPS, so the store need not run on this host. The root token never reaches a file, an argument list or an environment variable of this process.
+
+**Usage:** `swarmctl bao <COMMAND>`
+
+###### **Subcommands:**
+
+* `init` — Initialise the store, printing its keys and the root token once
+* `grant-bootstrap` — Bootstrap the granter: the one-time step that lets `swarm-bao-granter-role` write every `swarm-*` policy and role
+
+
+
+## `swarmctl bao init`
+
+Initialise the store, printing its keys and the root token once.
+
+Prints the unseal or recovery keys and the root token to stdout, once, and stores none of them: record them off this host before doing anything else. Refuses an initialised store.
+
+**Usage:** `swarmctl bao init [OPTIONS]`
+
+###### **Options:**
+
+* `--and-grant` — Right after initialising, bootstrap the granter in this same process, with the root token held only in memory.
+
+   Waits for the store to unseal itself first, so the store must unseal itself (a `pkcs11` seal); with a `shamir` seal, unseal by hand and run `swarmctl bao grant-bootstrap`.
+* `--bao-bin <PATH>` — `bao` binary to run. Defaults to `bao` on `PATH`, which on a host that runs the store is the wrapper that already carries the store's address, CA and client certificate
+* `--bootstrap-token-file <PATH>` — Where to write the 24h bootstrap token (mode 0600) for `swarm-bao-granter-role` to pick up. Must be a path on the host running that unit
+* `--bootstrap-policy <PATH>` — The `bao-bootstrap` policy file written to the store
+
+
+
+## `swarmctl bao grant-bootstrap`
+
+Bootstrap the granter: the one-time step that lets `swarm-bao-granter-role` write every `swarm-*` policy and role.
+
+Reads the root token from a hidden prompt, or from stdin when stdin isn't a terminal; never from an argument or an environment variable. Writes the `bao-bootstrap` policy, places a 24h grant token for the granter unit and restarts it, so run it as root on the host running that unit. Says so and does nothing when the granter exists already.
+
+**Usage:** `swarmctl bao grant-bootstrap [OPTIONS]`
+
+###### **Options:**
+
+* `--bao-bin <PATH>` — `bao` binary to run. Defaults to `bao` on `PATH`, which on a host that runs the store is the wrapper that already carries the store's address, CA and client certificate
+* `--bootstrap-token-file <PATH>` — Where to write the 24h bootstrap token (mode 0600) for `swarm-bao-granter-role` to pick up. Must be a path on the host running that unit
+* `--bootstrap-policy <PATH>` — The `bao-bootstrap` policy file written to the store
+
+
+
 ## `swarmctl login`
 
 Log in to the swarm named by `--swarm` as your own SSO account.