Repository navigation
feat(sensitive): step-ca as the tier's own CA, issuing to Caddy over ACME (#130) - #432
Merged
Merged
Conversation
…ACME (#130) The foundation commit said step-ca would be an intermediate beneath the lab CA, so nothing would be re-pointed. It was written before anyone read the root: gen-certs.sh mints it with pathlen:0, and a leaf beneath any intermediate of it fails "path length constraint exceeded" — measured with the pinned step-ca image against a throwaway root shaped by the same openssl line. ADR-0035 records the measurement, counts the cost of re-rooting the estate instead, and decides the tier gets a root of its own: the audiences are different (household devices versus the operator), the precedent is already set (.sops.yaml and ADR-0020 give separate trust separate keys), and a compromised trinity then forges only what trusts the tier's root. What this adds: - scripts/tier-ca.sh and `make tier-ca`: --mint runs `step ca init` in the pinned image on the monitoring host, adds the ACME provisioner offline (tls-alpn-01 only, seven-day leaves), proves the result (chain verifies, root is a CA, ca.json carries the expected claims and only /home/step paths, the bundle holds no root key), and writes a bundle for trinity; --install populates the step-ca-data volume from it with compose's labels so `make up` adopts the volume silently, and writes certificates/tier-ca.pem. The root key never leaves the monitoring host; --install refuses a bundle that carries it. - Caddyfile: a global `cert_issuer acme` block against step-ca's directory, trusting the tier's root; one site block per name; the catch-all keeps /healthz and the 404; fallback_sni for the healthcheck's SNI; the redirect listener on 80 disabled since 80 is not published. - compose.yaml: Caddy mounts only the tier's root and carries a network alias for every name it serves — step-ca validates the challenge by dialling the name from inside the compose network. step-ca keeps NET_BIND_SERVICE: the binary ships with that file capability and the kernel refuses to exec it against a bounding set without it (the first boot failed on "operation not permitted"; the foundation never booted). - render-config.sh's missing-certificates error is stack-aware, so on trinity it no longer names the command that would mint a third CA. - gen-certs.sh and generate-certificates.md are rescoped to the estate's CA, with the two-CA table up front and pathlen:0 commented as deliberate; build-the-tier-ca.md is the tier's procedure; successor-handover.md names both keys and the seven-day outage budget. Proved end to end on the monitoring host under a throwaway compose project: step-ca healthy, Caddy obtained a seven-day leaf for trinity.matrix.elysium over tls-alpn-01, the handshake verified against tier-ca.pem, only 443 listening. Every check in `make validate` passes. Left for the host (#404): the real mint and install. Filed #426 for a TLS-expiry rule sized for seven-day leaves — the estate's would page permanently. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…icate-authority-893481 # Conflicts: # README.md # stacks/sensitive/Caddyfile # stacks/sensitive/README.md # stacks/sensitive/compose.yaml
… into gerrrt/step-ca-certificate-authority-893481 # Conflicts: # README.md # scripts/render-config.sh
…AdGuard Home and Immich on the ACME shape Both landed on the hand-issued-leaf shape this branch retires. Each keeps its route as a site block of its own and gains a Caddy alias, the SAN prose goes, and Immich's README paragraph now names the tier's root rather than the estate's ca.pem. Main's Caddyfile had lost the Immich route in its own merges while its README still promised https://immich.matrix.elysium; the block is restored here against immich-server:2283. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…Paperless-ngx on the ACME shape Its route becomes a site block of its own with a Caddy alias; the SAN prose goes with the leaf it described. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…Vaultwarden on the ACME shape Site block of its own, an alias on Caddy, and the SAN prose goes with the leaf it described. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…icate-authority-893481 # Conflicts: # README.md
This was referenced Sep 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Towards #130. Second in the tier's build order, after #129's foundation.
The premise was wrong, and it was measured before deciding
The foundation commit (and its README, and the roadmap) said step-ca would be an intermediate beneath the lab CA so that nothing is re-pointed.
gen-certs.shmints that root withpathlen:0. Trial against a throwaway root shaped by the sameopensslline, in the pinned step-ca image:step ca init --root ca.pem --key ca-key.pem …openssl verifyon the intermediate aloneOKerror 25 at 2 depth lookup: path length constraint exceededEvery client here is Go's
crypto/x509and enforces the same. ADR-0035 records the measurement, counts the cost of re-rooting the estate instead (Grafana ×2, the lab guest via the Mac, every device that importedca.pem), and decides the tier gets a root of its own — the audiences differ (household devices vs the operator), the precedent is set (.sops.yaml, ADR-0020), and a compromisedtrinitythen forges only what trusts the tier's root.What the issue asked, answered
trinity—ca.jsonnever references it (checked by the script), the bundle that ships is built by naming files and--installrefuses one carrying the root key. Encrypted at rest withSTEPCA_PASSWORD, which lives in the tier's SOPS file that the monitoring host cannot decrypt, so using the root is a two-host operation on purpose. Backed up with the age key's offline copy; loss costs a re-root, not an outage, because the intermediate issues for its whole lifetime without it. Putting it in git under SOPS is rejected — that is the artefact that was purged from history.cert_issuer acmein the Caddyfile,tls-alpn-01only (80 stays unpublished, ADR-0012), seven-day leaves — the lifetime is the outage budget between step-ca dying and handshakes failing, and 24h gives a weekend nothing. Every served name is also a network alias of Caddy, because step-ca validates by dialling the name from inside the compose network.gen-certs.shand the runbook. Rescoped, not retired: they are the estate's CA, Grafana does not speak ACME. The runbook opens with the two-CA table;pathlen:0is commented as deliberate;build-the-tier-ca.mdis the tier's procedure;render-config.sh's error no longer names the command that would mint a third CA ontrinity.Proved, not assumed
Booted on the monitoring host under a throwaway compose project (
TIER_CA_PROJECT) against a throwaway root: step-ca healthy, Caddy obtained a seven-day leaf fortrinity.matrix.elysiumovertls-alpn-01, the handshake verified againsttier-ca.pemwithVerify return code: 0,/healthzand the 404 answered, only 443 listening. Two things that first boot found, which the foundation never had a chance to:step ca initwrites absolute paths intoca.json, so the tree must be minted at/home/step; and step-ca's binary carries theNET_BIND_SERVICEfile capability, socap_drop: [ALL]alone makes the exec fail withoperation not permitted— it keeps that one capability now, with the measurement in the comment.make validatepasses in full.Security review
certificates/; the script proves the bundle holds no root key;check-tracked-artefacts.shand the gitleaks PEM rule stand behind itLeft open
trinity, under Build the sensitive-tier host on the ProDesk (ADR-0034) #404 (the host does not exist).stacks/sensitive/Caddyfileandcompose.yamlon the oldtls cert keyshape; each has been messaged with the new one (site block per name + a caddy alias per name). Whoever merges second rebases.🤖 Generated with Claude Code