# 0096. A Secret reference is set or changed only with update on the resource's secret-references

Status: Accepted · Date: 2026-10-27 · Design section: Security, RBAC · Extends: 0094

Decided: any create or update that sets or changes a field naming a Secret needs the verb `update` on the subresource `secret-references` of that resource (`talosclusters/secret-references`, `talosetcdbackups/secret-references`), asked of the requesting user with a SubjectAccessReview in the validating webhook that already gates `spec.authentication`; the controller and the GitOps engines are exempt as there; writing the same value again is not gated and neither is removing a reference; `ichor-admin` holds the right, `ichor-operator` and `ichor-viewer` do not, and the ichor-ui ServiceAccount does not need it

## Context

ADR 0094 gives `ichor-operator` `update` and `patch` on `talosclusters` and `talosmachines` and gates `spec.authentication` alone. But several spec fields name a Secret that the controller (or the UI backend) then reads with its own, broader privileges, in its own namespace. An operator who may edit a cluster could repoint such a field at any Secret in that namespace and make Ichor use it: for a registry's `authSecretRef` the controller copies the Secret's password-shaped keys into the node's machine config, which the operator can then read back. Editing the object was meant to be the operator's right; choosing which Secret Ichor reads was not.

## The audit

`rg -n "SecretRef|secretRef|SecretKeyRef" api/` finds four fields. Nothing on `TalosMachine`, `TalosConfigPatch`, `TalosStorage`, `TalosOperation`, `IchorUser` or `IchorInstallation` names a Secret.

| Field | Read by | Why it is sensitive |
| --- | --- | --- |
| `TalosCluster.spec.secretsRef` | controller, UI backend (credentials download), `ichor` CLI | Names the Secret holding the Talos, Kubernetes and etcd CA bundle. Repointing it makes the controller sign node configs and the etcd backup key with another Secret, or reads a bundle the caller should not see back through the credentials download. |
| `TalosCluster.spec.registries[].authSecretRef` | controller, at render time | Its password, auth and identityToken keys are written into the node's machine config. An operator could exfiltrate any Secret of the Ichor namespace that has such keys into a config they can read. |
| `TalosCluster.spec.gitops.repository.tokenSecretRef` | UI backend, in its own namespace | The token pushes branches and opens pull requests. Repointing it makes the backend act with another Secret's token (a Git host token chosen by the editor), or with a different key of the same Secret. |
| `TalosEtcdBackup.spec.destination.s3.credentialsSecretRef` | controller, in its own namespace | The S3 credentials the snapshots are written and pruned with. Repointing it sends every snapshot, and the prune, to credentials of the editor's choosing. |

## Decision

**The right is `update` on `<resource>/secret-references`.** The same shape as ADR 0094's `talosclusters/authentication`: a subresource that exists only as an RBAC name. The webhook (`vauthentication-v1alpha1.kb.io`, which already receives `talosclusters` create and update) runs the check first, and a new rule `vsecretrefs-v1alpha1.kb.io` sends `talosetcdbackups` create and update to the same handler. The check is a SubjectAccessReview as the requesting user, so a hand-written CR obeys it as the CLI and UI do.

**What counts as a change.** On create, a reference that is set. On update, a reference whose value differs from the stored one (for the token, name or key). For `registries[]`, entries are matched by `host`: an `authSecretRef` that is new or names another Secret is a change. A removed reference is not a change: it only stops Ichor using a Secret. A write that leaves every reference as it was, the UI's upgrade write for one, is never asked.

**Who is exempt.** The controller's identity and the GitOps engines (`ExemptUsers`), exactly as for the authentication gate: the engines apply what a person reviewed in Git, and the controller never changes `spec`.

**Roles.** `ichor-admin` gets `update` on `talosclusters/secret-references` and `talosetcdbackups/secret-references` (kustomize role and chart template, kept equal by the role test). `ichor-operator` does not. The ichor-ui ServiceAccount does not: with OIDC on the backend writes as the user; with it off the backend's writes (upgrades, machine approval, patches) leave the references as they were, and the webhook does not ask for an unchanged value. A cluster created by `ichor init` sets `secretsRef`, so it needs an administrator, as creating the bundle's Secret already does.

## Consequences

An operator can no longer change where Ichor reads credentials from; setting one up (a new registry credential, an S3 bucket) is an administrator's step, and the operator keeps editing everything else. The check adds a SubjectAccessReview to a write only when a reference is touched. GitOps users change a reference through Git, reviewed there. A reference to a Secret the author may not read is still possible for an administrator; narrowing that (an allow-list of Secret names) is left out.