pilot-ca

Documentation

Overview

pilot-ca — offline tooling for the Pilot Protocol root CA used to authenticate beacon WSS endpoints in compat mode.

The root CA private key is the trust anchor for every compat-mode daemon's TLS handshake. It must never leave the operator's secure machine (Yubikey-backed or air-gapped). This binary is the only production code that touches it.

Subcommands:

pilot-ca init-root <out-dir>
   Generate a fresh Ed25519 root CA keypair + self-signed root cert.
   Writes <out-dir>/root.key (mode 0600) and <out-dir>/root.crt.
   The .key file must be moved to offline storage immediately.

pilot-ca issue-beacon <root-dir> <hostname> <out-dir>
   Sign a leaf cert for a beacon hostname using the root CA in
   <root-dir>. Writes <out-dir>/<hostname>.key and <out-dir>/<hostname>.crt.
   Leaf certs are P-256 ECDSA (TLS-friendly) with SAN = hostname.
   Validity: 90 days. Re-run before expiry; Caddy reloads
   automatically on file change.

pilot-ca verify <root.crt> <leaf.crt>
   Confirm a leaf cert chains to the root and is currently valid.
   Exit 0 on success.

The root cert (PEM) is what gets embedded in pilot-daemon via //go:embed. The root key stays offline. Beacon operators receive only the leaf cert + leaf key.