feat(sec): provision the narrow conformance CI trigger credential -- and refuse to arm a fake green #19
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Home-Network/home-network-k3s-impl#19
Reference in new issue
Block a user
Rebased 2026-09-29 — the
DECISIONS-LOG.mdappend is why this PR was unmergeableThis PR no longer touches
DECISIONS-LOG.mdat all. The handoff it used to append to thatfile's tail now lives in its own file,
decisions/2026-09-29-conformance-trigger-kubeconfig.md.Why:
DECISIONS-LOG.mdwas append-only and every branch appended to the same last hunk, so notwo concurrent branches could auto-merge. Measured against the live Gitea on 2026-09-29, four of
the five open PRs were
mergeable: falseandDECISIONS-LOG.mdwas the only conflicting pathin all four. This PR (#19) was one of them. Nothing was wrong with the change itself — the log's
storage format serialised work that was otherwise parallel. The workflow fix is PR #24
(one entry per file under
decisions/, with the old file frozen and its SHA-256 pinned).What changed in the rebase:
main(cadf64a).infra/gitea/README.mdandinfra/gitea/conformance-trigger-kubeconfig.share byte-identical to the original threecommits — verified with
git diffagainst the old head.DECISIONS-LOG.mdhunk (~99 lines) is gone;git diff origin/main...HEAD --name-onlynowlists only
decisions/2026-09-29-conformance-trigger-kubeconfig.md,infra/gitea/README.md,infra/gitea/conformance-trigger-kubeconfig.sh.DECISIONS-LOG.md(the measurement that this PR's CI hasno
approval-policycheck) was dropped as a commit; its substance is carried into the new entryverbatim in meaning, including every
UNVERIFIEDit recorded. Nothing was upgraded into aclaim. The script is still UNEXECUTED.
git merge-tree --write-tree origin/main HEADreports no conflict, and this PR mergescleanly against today's
mainon its own — it does not depend on #24 landing first (it alsomerge-tree's clean against #24's branch, since the paths are disjoint).
Gate re-run after the rebase (pinned toolbox, agent worktree,
DEV_KUBECONFIG=/dev/nullplusthe
ENGINEbind-mount shim):MERGE GATE: UNDETERMINED, rc 3, diff baseorigin/main @ c59fe9f923c4...HEAD @ ad5de2dba9fe, touched requirementR-ENV-01.spec-immutability,decisions-log,lint,l0,render-golden,l1all green; the gatedecision names exactly one stage that did not run —
gitea-settings(SETTINGS_API_TOKENunwired repo-wide). The
conformancestage also reported SKIPPED (CLUSTER_AVAILABLE!=true,Phase 0). PR #24 merged to
mainwhile this rework was in flight, so the newdecisions-logstage did run, and it validated this PR's entry: "archive frozen, 2 entries well-formed", with
DECISIONS-LOG.mdunchanged and matchingdecisions/ARCHIVE.sha256.rc 3 is UNDETERMINED, not green. This supersedes the gate paragraph further down, which was
written before the rebase and reported
spec-immutabilityas a second skip.Implements
docs/plans/l2-l3-conformance-ci-wiring.md§3 item 6 (= §5 step 7) as an operator script:infra/gitea/conformance-trigger-kubeconfig.sh, plus its section ininfra/gitea/README.mdand a handoff entry (nowdecisions/2026-09-29-conformance-trigger-kubeconfig.md— see the rebase note at the top).It is UNEXECUTED. Minting a cluster credential and changing Gitea variables are operator actions. Nothing was minted, no Gitea object was written, no mutating
kubectlwas run. Everything below is a claim about the script, not about the platform.What it does
Mints a token for
conformance/conformance-trigger(TokenRequest), wraps only that token with the cluster CA and server into a kubeconfig, stores it as the Actions secretCONFORMANCE_TRIGGER_KUBECONFIG, and setsvars.CLUSTER_AVAILABLEonly as a separately-requested, precondition-gated, TTY-confirmed final step.Never a cluster-admin kubeconfig, never a copy of the operator's own — only
.clusterfields are read from the operator context; its client cert/key are not copied. The token is never printed and never reachesargv: it goes into a 0600 file in a 0700 temp dir and into the PUT body file (--data @file). The script refuses to run underset -x, because xtrace would print it.The two traps this repo already paid for
GITEA_is a reserved secret-name prefix (HTTP 400invalid secret name). The name isCONFORMANCE_TRIGGER_KUBECONFIG, which is also whatgate.ymlandmerge-gate.yamlalready reference.curl -sSexits 0 on an HTTP error. Every write checks%{http_code}and reads the object back. The secret read-back proves presence by name only — Gitea never returns secret values — and the script says so rather than implying its content was checked. The variable read-back asserts the value is exactlytrue, which is whatgate.ymlcompares against.Preconditions are split in two, and the split is the security argument
conformance-trigger-job-shapepresent +Enforce+failurePolicy: Fail+ ReadyCONFORMANCE_RUNNER_IMAGE;initContainers+ the admitted image inchainsaw-job.yaml;CONFORMANCE_TRIGGER_KUBECONFIGinci/conformance.shcode, not a commentCLUSTER_AVAILABLEMint-blocking, because Kubernetes places no
usecheck on a Job'sserviceAccountName: acreate jobstoken in that namespace is the privilegedconformance-runneridentity unless admission bounds its shape. RBAC cannot close that (plan §4); minting before the boundary is live hands CI the escalation the boundary exists to close.Arm-blocking separately, because storing the secret early is harmless (the job is gated off) and is the plan's own order.
All three arm-blocking checks fail in the tree today, so a live run would store the secret and then refuse to arm
CLUSTER_AVAILABLE, naming each missing item. That is intended: measured 2026-09-29,CLUSTER_AVAILABLE=truewith no trigger path scaffold-skipped all 54 tests at rc 0 and the stage printed "L2/L3 conformance passed".ci/conformance.shnow blocks that case, so arming early does not enable L2/L3 — it only breaks every PR. Arming needs the explicit flag, every precondition green, and a typed confirmation on a TTY.The credential is proven narrow before anything is stored
auth whoamimust returnsystem:serviceaccount:conformance:conformance-trigger; a realget jobsround-trip must succeed; then anauth can-imatrix asserts both halves — granted (create/get jobs,get pods,get pods/log) and denied (delete jobs,create pods/exec,get secrets,create jobsindefault,get nodes,'*' '*' --all-namespaces). A mismatch aborts before any store, and the message says explicitly not to widenconformance/incluster/rbac.yamlto make it pass. That file is untouched here.Unverified, because it was not run
bash -n(clean) and careful reading.shellcheckis not on the host and the gate has no shellcheck stage.value— notdataas for secrets) is from documentation, not measurement. The script tries POST, falls back to PUT, prints the response body on failure, and treats the read-back as the authority..status.readyor aReadycondition; "neither present" blocks rather than assuming ready.--server, and a hard refusal on a loopback address.expclaim rather than trusting--duration(the API server caps it) — that decode path is also unexercised.Gate (pinned toolbox, from the agent worktree)
MERGE GATE: UNDETERMINED, rc 3, on this exact commit.lint,l0,render-golden,l1green; touched requirementR-ENV-01. Stages that did not run:spec-immutability(sibling spec repo absent — the documented tolerated skip) andgitea-settings(SETTINGS_API_TOKENis a credential this agent does not hold). Neither was "fixed";gate.ymltolerates exit 3.Measured CI on this PR (not assumed)
The brief for this work expected an
approval-policycheck to FAIL becauseinfra/gitea/**is security-relevant. No such check exists onmain—.gitea/workflows/holds onlygate.ymland the dormantmerge-gate.yaml, andci/approval-policy.shis absent. Since confirmed by the coordinator: it is added by PR #17, still unmerged. So today nothing machine-enforces "security-relevant paths need a human"; that rule rests onrequired_approvals: 1plus a reviewer reading the diff. Re-measure once #17 lands — this PR touchesinfra/gitea/**and would then be exactly the case that check is for.A green
gatetick is not a claim that this script works: the gate never executesinfra/gitea/**, and the L2/L3 stage skipped. Read the "Unverified" section above.Also in this PR: the README's illegal secret name (commit 3)
infra/gitea/README.mdstill namedGITEA_SETTINGS_TOKEN— the name PR #15 replaced withSETTINGS_API_TOKENprecisely because Gitea reserves theGITEA_prefix and rejects it with HTTP 400invalid secret name. The file documenting that story was still repeating the illegal name, in its behaviour table and in its closing "remaining step" line. Both fixed, folded in here because this PR already owns that file.The note records what
ci/gitea-settings.shactually does, quoted from the file rather than assumed:So
GITEA_SETTINGS_TOKENis still honoured, but only as an environment variable for a local run — it can never be the CI wiring, because the secret that would feed it cannot be created at all. Documentation only; no behaviour change.Noted, not fixed — same defect, different file
ci/gitea-settings.sh:45still instructs the reader to "create a Gitea repo secretGITEA_SETTINGS_TOKEN", which is impossible for the same reason. That file is outside this PR's diff, so it is left for a one-line change rather than widening a security-reviewed diff.🤖 Generated with Claude Code
docs/plans/l2-l3-conformance-ci-wiring.md §3 item 6, as an operator script: infra/gitea/conformance-trigger-kubeconfig.sh. UNEXECUTED here -- minting a cluster credential and changing Gitea variables are operator actions. It mints a token for conformance/conformance-trigger (TokenRequest), wraps ONLY that token with the cluster CA and server into a kubeconfig, and stores it as the Actions secret CONFORMANCE_TRIGGER_KUBECONFIG. Never cluster-admin, never a copy of the operator's own kubeconfig. The token is never printed and never reaches argv: it goes into a 0600 file and into the PUT body FILE (--data @file), and the script refuses to run under `set -x` because xtrace would print it. Two traps this repo already paid for are designed around: * GITEA_ is a RESERVED secret-name prefix (HTTP 400 "invalid secret name"), so the name is CONFORMANCE_TRIGGER_KUBECONFIG -- which is also what gate.yml and merge-gate.yaml already reference. * `curl -sS` exits 0 on an HTTP error. Every write checks %{http_code} AND reads the object back. The secret read-back proves presence by NAME only (Gitea never returns secret values) and the script says so rather than implying its content was checked; the variable read-back asserts the value is exactly "true", which is what gate.yml compares against. PRECONDITIONS ARE SPLIT IN TWO, and the split is the security argument: mint-blocking (cluster) -- SA/Role/RoleBinding present, and ClusterPolicy conformance-trigger-job-shape present + Enforce + failurePolicy Fail + Ready. Any failure and NOTHING IS MINTED. Kubernetes places no `use` check on a Job's serviceAccountName, so a `create jobs` token in that namespace IS the privileged conformance-runner identity unless admission bounds its shape. RBAC cannot close that (plan §4); minting before the boundary is live hands CI the escalation the boundary exists to close. arm-blocking (repo) -- digest-pinned CONFORMANCE_RUNNER_IMAGE, an initContainer plus the admitted image in chainsaw-job.yaml, and CONFORMANCE_TRIGGER_KUBECONFIG referenced in ci/conformance.sh CODE rather than a comment. These block only vars.CLUSTER_AVAILABLE, because storing the secret early is harmless (the job is gated off) and is the plan's own order. All three arm-blocking checks FAIL in the tree today, so a live run would store the secret and then REFUSE to arm CLUSTER_AVAILABLE, naming each missing item. That is the intended behaviour: measured 2026-09-29, CLUSTER_AVAILABLE=true with no trigger path scaffold-skipped all 54 tests at rc 0 and the stage printed "L2/L3 conformance passed". ci/conformance.sh now blocks that case, so arming early does not enable L2/L3 -- it only breaks every PR. Arming needs the explicit flag, every precondition green, and a typed confirmation on a TTY. Before storing anything, the credential is PROVEN narrow: auth whoami must be system:serviceaccount:conformance:conformance-trigger, a real `get jobs` round-trip must succeed, and an auth can-i matrix asserts both halves -- granted (create/get jobs, get pods, get pods/log) and DENIED (delete jobs, create pods/exec, get secrets, create jobs in default, get nodes, '*' '*' --all-namespaces). A mismatch aborts before any store, and says explicitly not to widen conformance/incluster/rbac.yaml to make it pass. Verified only by `bash -n` (clean) and reading. The Gitea variables API shape (POST creates, PUT updates, body field `value` not `data`) is from documentation, not measurement: the script tries POST then PUT, prints the response body on failure, and treats the read-back as the authority. Kyverno readiness is accepted from either .status.ready or a Ready condition, and "neither present" blocks rather than assuming ready. Gate (pinned toolbox): MERGE GATE: UNDETERMINED (rc 3) -- spec-immutability and gitea-settings unrun, the expected local result. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>9275dae6e0to7f5a32f6297f5a32f629toad5de2dba9