Skip to content

Commit 3cb9192

Browse files
fix(marketplace): pin a tapped repository to a digest instead of a mutable tag (#5082)
## What this PR does A tapped (community-connected) repository followed a mutable OCI tag: the Flux `OCIRepository` carried only `spec.ref.tag` with a 5-minute interval, so whoever controlled the tag controlled what ran in the management cluster within that interval, down to the HelmReleases of already-running tenant application instances. Fixes #4979. A tap is now pinned to a digest. `cozypkg tap` and the connect API accept an explicit `oci://host/org/repo@sha256:...` reference; a tag reference is resolved and pinned to its digest by the tap materializer once the artifact for the current spec generation is ready, from the digest Flux reports in `status.artifact.revision`, with the tag kept informational. A tap connected before this change is pinned to its current digest on the first reconcile after upgrade, and a re-connect to a new tag waits for source-controller to re-resolve before pinning, so a stale revision is never pinned. Moving the tag upstream no longer changes anything in the cluster; an explicit re-connect moves the pin. Connect also accepts an optional keyless cosign verification policy (`--certificate-identity` / `--certificate-oidc-issuer` on the CLI, `spec.verify` on the API), anchored to an exact identity so a superstring cannot match, and preserves it, and the pull secret, across repeat connects rather than silently dropping them. With those flags the CLI verifies the signature at tap time and pins the verified digest before pulling, so the content it applies is what a trusted identity signed; it fails closed if the verified digest cannot be determined. ### Screenshots Not applicable: no UI changes. ### Downstream repositories I walked the trigger map against the diff. The change is confined to `cozypkg`, the `Tap` aggregated API (a virtual, cluster-scoped resource with no CRD), the tap materializer, and the community-index docs. It does not touch `packages/apps`, `packages/core/platform/values.yaml`, installer values, platform variants/components, release assets, `ApplicationDefinition` semantics, the `hack/` make targets, or the commit convention, so the provider, ansible, ccp and external-apps paths are not reached. One path is arguable and needs a human decision, so I have left every box unticked rather than tick or dismiss it: - `cozystack/website` — `cozypkg tap` gains flags and digest-pinning behaviour. The marketplace tap flow is new and I am not sure it has a reference page on the site yet, so whether a docs follow-up is warranted (and where) is a maintainer call. - [ ] No downstream repository is affected by this change - [ ] [cozystack/website](https://github.com/cozystack/website) - follow-up: - [ ] [cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack) - follow-up: - [ ] [cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack) - follow-up: - [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up: - [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up: - [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) - follow-up: - [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) - follow-up: - [ ] [cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server) - follow-up: - [ ] [cozystack/external-apps-example](https://github.com/cozystack/external-apps-example) - follow-up: - [ ] [cozystack/examples](https://github.com/cozystack/examples) - follow-up: - [ ] [cozystack/community](https://github.com/cozystack/community) - follow-up: ### Release note ```release-note fix(marketplace): a tapped repository is pinned to a digest instead of following a mutable tag, so moving the tag upstream no longer changes what runs in the cluster; connect accepts oci://...@sha256:... and an optional keyless cosign verify policy (anchored to an exact identity and preserved across re-connects), and with verify flags the CLI verifies the signature and pins the verified digest at tap time. ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## Summary by CodeRabbit - **New Features** - OCI repositories can be connected using a SHA-256 digest, with or without a tag. Tag-based sources are pinned to the resolved artifact digest. - Optional Cosign keyless verification is available during connection using certificate identity and OIDC issuer details. - Reconnecting preserves existing verification and pull-credential settings when replacement values aren’t provided. - **Bug Fixes** - Reconnecting with a new tag clears previous operator-managed pins so the requested tag can resolve to its current artifact. - **Documentation** - Clarified tag pinning, signature verification, and where tapped app charts run. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Backported-from: 94ada11
2 parents 832e85b + 9cff86f commit 3cb9192

13 files changed

Lines changed: 985 additions & 69 deletions

File tree

‎cmd/cozypkg/cmd/tap.go‎

Lines changed: 167 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ var tapCmdFlags struct {
5555
kubeconfig string
5656
index string
5757
skipValidate bool
58+
certIdentity string
59+
certIssuer string
5860
}
5961

6062
// ociRef is the parsed form of an oci:// reference.
@@ -65,10 +67,28 @@ type ociRef struct {
6567
// Repo is the last path segment.
6668
Repo string
6769
Tag string
70+
// Digest, when set, pins the exact content (sha256:<64 hex>). It takes
71+
// precedence over Tag at pull time (Flux resolves digest before tag), so a
72+
// digest-pinned reference never follows a moved tag.
73+
Digest string
74+
}
75+
76+
// pullRef is the reference to pull: by digest when one is pinned (so the pull
77+
// resolves the exact content regardless of where the tag points), otherwise by
78+
// tag.
79+
func (r ociRef) pullRef() string {
80+
if r.Digest != "" {
81+
return r.URL + "@" + r.Digest
82+
}
83+
return r.URL + ":" + r.Tag
6884
}
6985

7086
var sanitizeName = regexp.MustCompile(`[^a-z0-9-]+`)
7187

88+
// ociDigestRe matches a full OCI manifest digest (sha256:<64 hex>), the same
89+
// shape the platform source's "digest=" reference enforces.
90+
var ociDigestRe = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`)
91+
7292
// parseOCIRef splits an oci:// reference into its URL (without tag), org, repo,
7393
// and tag. A missing tag defaults to "latest".
7494
func parseOCIRef(ref string) (ociRef, error) {
@@ -77,11 +97,20 @@ func parseOCIRef(ref string) (ociRef, error) {
7797
}
7898
body := strings.TrimPrefix(ref, "oci://")
7999

80-
tag := ""
81-
// Digest pins are not tag-addressable; tap is tag-based for now.
82-
if strings.Contains(body, "@") {
83-
return ociRef{}, fmt.Errorf("digest references are not supported by tap yet; use a tag (oci://host/org/repo:tag)")
100+
// A digest pins the exact content (oci://host/org/repo@sha256:...). An
101+
// optional tag may precede it and is then informational only. The digest
102+
// must be a full sha256:<64 hex>, the same contract the platform source's
103+
// "digest=" reference enforces.
104+
digest := ""
105+
if at := strings.LastIndex(body, "@"); at >= 0 {
106+
digest = body[at+1:]
107+
body = body[:at]
108+
if !ociDigestRe.MatchString(digest) {
109+
return ociRef{}, fmt.Errorf("invalid digest %q in reference %q: want sha256:<64 hex>", digest, ref)
110+
}
84111
}
112+
113+
tag := ""
85114
if colon := strings.LastIndex(body, ":"); colon >= 0 && !strings.Contains(body[colon:], "/") {
86115
tag = body[colon+1:]
87116
body = body[:colon]
@@ -96,10 +125,11 @@ func parseOCIRef(ref string) (ociRef, error) {
96125
if len(segs) >= 3 {
97126
org = segs[len(segs)-2]
98127
}
99-
if tag == "" {
128+
// Default to latest only when neither a tag nor a digest pins the content.
129+
if tag == "" && digest == "" {
100130
tag = "latest"
101131
}
102-
return ociRef{URL: "oci://" + body, Org: org, Repo: repo, Tag: tag}, nil
132+
return ociRef{URL: "oci://" + body, Org: org, Repo: repo, Tag: tag, Digest: digest}, nil
103133
}
104134

105135
// fluxSourceName is the RFC-1123 name of the OCIRepository tap creates. It
@@ -116,9 +146,11 @@ func fluxSourceName(r ociRef) string {
116146
}
117147

118148
// buildTapOCIRepository mirrors the operator's generateOCIRepository: an
119-
// OCIRepository in cozy-system, 5m interval, optional tag reference, optional
120-
// pull-credential secretRef (the private-tap credential, symmetric with #2472).
121-
func buildTapOCIRepository(name string, r ociRef, secret string) *sourcev1.OCIRepository {
149+
// OCIRepository in cozy-system, 5m interval, a tag and/or digest reference,
150+
// optional pull-credential secretRef (the private-tap credential, symmetric
151+
// with #2472). A tag-only reference is pinned to a digest later by the tap
152+
// materializer; an explicit digest is pinned here at connect time.
153+
func buildTapOCIRepository(name string, r ociRef, secret string, verify *sourcev1.OCIRepositoryVerification) *sourcev1.OCIRepository {
122154
obj := &sourcev1.OCIRepository{
123155
TypeMeta: metav1.TypeMeta{
124156
APIVersion: sourcev1.GroupVersion.String(),
@@ -134,19 +166,62 @@ func buildTapOCIRepository(name string, r ociRef, secret string) *sourcev1.OCIRe
134166
Annotations: map[string]string{tapconst.NameAnnotation: name},
135167
},
136168
Spec: sourcev1.OCIRepositorySpec{
137-
URL: r.URL,
138-
Interval: metav1.Duration{Duration: 5 * time.Minute},
139-
Reference: &sourcev1.OCIRepositoryRef{
140-
Tag: r.Tag,
141-
},
169+
URL: r.URL,
170+
Interval: metav1.Duration{Duration: 5 * time.Minute},
171+
Reference: &sourcev1.OCIRepositoryRef{Tag: r.Tag, Digest: r.Digest},
142172
},
143173
}
144174
if secret != "" {
145175
obj.Spec.SecretRef = &fluxmeta.LocalObjectReference{Name: secret}
146176
}
177+
if verify != nil {
178+
obj.Spec.Verify = verify
179+
}
147180
return obj
148181
}
149182

183+
// carryoverSourceFields preserves an existing tap source's verification policy
184+
// and pull credential when this invocation did not set them from flags, so a
185+
// re-tap (e.g. to move the pin to a new tag) never silently drops signature
186+
// verification or the pull secret. A server-side apply that omits a field this
187+
// field owner previously set would otherwise remove it, which the API connect
188+
// path (rest.go) deliberately avoids; this keeps the CLI symmetric with it.
189+
func carryoverSourceFields(obj, existing *sourcev1.OCIRepository, flagVerify *sourcev1.OCIRepositoryVerification, flagSecret string) {
190+
if existing == nil {
191+
return
192+
}
193+
if flagVerify == nil && existing.Spec.Verify != nil {
194+
obj.Spec.Verify = existing.Spec.Verify
195+
}
196+
if flagSecret == "" && existing.Spec.SecretRef != nil {
197+
obj.Spec.SecretRef = existing.Spec.SecretRef
198+
}
199+
}
200+
201+
// tapVerification builds a keyless cosign verification policy from the connect
202+
// flags, or nil when neither is set. Both the certificate identity (subject)
203+
// and the OIDC issuer are required together: a policy that verified a signature
204+
// without pinning who signed it would be worse than none. Both are Go regular
205+
// expressions at the Flux layer, so an exact identity should be anchored.
206+
func tapVerification(identity, issuer string) (*sourcev1.OCIRepositoryVerification, error) {
207+
if identity == "" && issuer == "" {
208+
return nil, nil
209+
}
210+
if identity == "" || issuer == "" {
211+
return nil, fmt.Errorf("keyless signature verification needs both --certificate-identity and --certificate-oidc-issuer")
212+
}
213+
// Flux treats Issuer and Subject as Go regexps, so anchor and quote them for
214+
// an exact match: an unanchored identity would also accept a superstring
215+
216+
return &sourcev1.OCIRepositoryVerification{
217+
Provider: "cosign",
218+
MatchOIDCIdentity: []sourcev1.OIDCIdentityMatch{{
219+
Issuer: "^" + regexp.QuoteMeta(issuer) + "$",
220+
Subject: "^" + regexp.QuoteMeta(identity) + "$",
221+
}},
222+
}, nil
223+
}
224+
150225
// rewritePackageSourceForTap prepares a PackageSource read from the artifact for
151226
// apply: it keeps the repository's own declared name (no community rename),
152227
// clears server-set metadata, stamps the tap marker (label + source annotation)
@@ -181,21 +256,38 @@ func rewritePackageSourceForTap(ps *cozyv1alpha1.PackageSource, sourceName, sour
181256
}
182257
}
183258

184-
// clearMaterializedRevision removes the operator's materialized-revision
185-
// annotation from the tap's OCIRepository, so the next reconcile does not
186-
// short-circuit on the unchanged artifact revision and re-materializes its
187-
// PackageSources (recovering one removed out-of-band). A no-op when the source or
188-
// the annotation is absent.
189-
func clearMaterializedRevision(ctx context.Context, k8sClient client.Client, srcName string) error {
259+
// resetTapPinState prepares a tap's OCIRepository for a re-tap. It clears the
260+
// materialized-revision annotation so the next reconcile does not short-circuit
261+
// on the unchanged revision and re-materializes its PackageSources (recovering
262+
// one removed out-of-band), and the pinned-digest annotation so the operator
263+
// re-pins the newly requested reference. For a tag-based re-tap (explicitDigest
264+
// false) it also drops the operator's prior digest pin from spec.ref: a
265+
// server-side apply under field owner cozypkg cannot clear a field the operator
266+
// owns, so a moved tag would otherwise stay pinned to the old digest. An
267+
// explicit-digest re-tap keeps the digest the apply itself set. A no-op (and no
268+
// error) when the source is absent or there is nothing to clear.
269+
func resetTapPinState(ctx context.Context, k8sClient client.Client, srcName string, explicitDigest bool) error {
190270
reg := &sourcev1.OCIRepository{}
191271
if err := k8sClient.Get(ctx, client.ObjectKey{Name: srcName, Namespace: cozySystemNamespace}, reg); err != nil {
192272
return client.IgnoreNotFound(err)
193273
}
194-
if _, ok := reg.Annotations[tapconst.MaterializedRevisionAnnotation]; !ok {
274+
base := reg.DeepCopy()
275+
changed := false
276+
if _, ok := reg.Annotations[tapconst.MaterializedRevisionAnnotation]; ok {
277+
delete(reg.Annotations, tapconst.MaterializedRevisionAnnotation)
278+
changed = true
279+
}
280+
if _, ok := reg.Annotations[tapconst.PinnedDigestAnnotation]; ok {
281+
delete(reg.Annotations, tapconst.PinnedDigestAnnotation)
282+
changed = true
283+
}
284+
if !explicitDigest && reg.Spec.Reference != nil && reg.Spec.Reference.Digest != "" {
285+
reg.Spec.Reference.Digest = ""
286+
changed = true
287+
}
288+
if !changed {
195289
return nil
196290
}
197-
base := reg.DeepCopy()
198-
delete(reg.Annotations, tapconst.MaterializedRevisionAnnotation)
199291
return k8sClient.Patch(ctx, reg, client.MergeFrom(base))
200292
}
201293

@@ -238,11 +330,18 @@ With --secret the OCIRepository is given a pull-credential secretRef (the
238330
admin pre-creates the Secret in cozy-system), so a private repository taps in
239331
one command.
240332
241-
Trust: tap validates the artifact's structure but does NOT verify its cosign
242-
signature. Signature verification is the community index's job at publication
243-
time ('cozypkg validate --require-signature' in the index CI gate, pinned to
244-
the entry's recorded identity), and can additionally be enforced at pull time
245-
via Flux OCIRepository verification. Installing an app from a tapped repository
333+
Pinning: a tapped repository does not follow a moving tag. A reference given by
334+
digest (oci://host/org/repo@sha256:...) is pinned to that digest immediately; a
335+
tag reference is pinned to the digest it currently resolves to as soon as the
336+
source materializes, with the tag kept informational. Moving the tag upstream
337+
changes nothing in the cluster; tap the repository again to move the pin.
338+
339+
Trust: tap validates the artifact's structure. Keyless signature verification at
340+
pull time is enabled with --certificate-identity and --certificate-oidc-issuer,
341+
which set a Flux cosign verify policy on the source so content is pulled only
342+
when signed by that identity. Signature verification at publication time is the
343+
community index's job ('cozypkg validate --require-signature' in the index CI
344+
gate, pinned to the entry's recorded identity). Installing an app from a tapped repository
246345
runs its charts in your management cluster: tap only sources you trust.`,
247346
Args: cobra.ExactArgs(1),
248347
RunE: func(cmd *cobra.Command, args []string) error {
@@ -256,12 +355,41 @@ runs its charts in your management cluster: tap only sources you trust.`,
256355
return err
257356
}
258357
if tapCmdFlags.tag != "" {
358+
if ref.Digest != "" {
359+
return fmt.Errorf("--tag cannot override the digest in %q; drop the digest or the --tag flag", args[0])
360+
}
259361
ref.Tag = tapCmdFlags.tag
260362
}
363+
verify, err := tapVerification(tapCmdFlags.certIdentity, tapCmdFlags.certIssuer)
364+
if err != nil {
365+
return err
366+
}
367+
368+
// With verification flags set, verify the signature now and pin the verified
369+
// digest, so the artifact we pull and the PackageSources we apply are the
370+
// exact content a trusted identity signed. Without this the CLI would apply
371+
// an unverified tag pull (only the Flux source would carry the policy), so a
372+
// moved tag could land unsigned PackageSource content in the cluster before
373+
// the operator re-materialized.
374+
if verify != nil {
375+
verifiedDigest, verr := verifyCosignSignature(ref.pullRef(), tapCmdFlags.certIdentity, tapCmdFlags.certIssuer)
376+
if verr != nil {
377+
return verr
378+
}
379+
// Fail closed: a verified signature with no parseable digest must not
380+
// fall back to an unpinned tag pull, which would reopen the tag-mutation
381+
// window between verify and pull.
382+
if verifiedDigest == "" {
383+
return fmt.Errorf("cosign verified %q but returned no manifest digest; refusing to pull by an unpinned tag", ref.pullRef())
384+
}
385+
if ref.Digest == "" {
386+
ref.Digest = verifiedDigest
387+
}
388+
}
261389

262390
// Pull first: an unreachable/invalid ref must fail before any cluster
263391
// resource is created (no half-created source).
264-
fullRef := ref.URL + ":" + ref.Tag
392+
fullRef := ref.pullRef()
265393
dir, cleanup, err := pullOCIArtifact(fullRef)
266394
if err != nil {
267395
return err
@@ -287,7 +415,7 @@ runs its charts in your management cluster: tap only sources you trust.`,
287415
}
288416

289417
srcName := fluxSourceName(ref)
290-
ociRepo := buildTapOCIRepository(srcName, ref, tapCmdFlags.secret)
418+
ociRepo := buildTapOCIRepository(srcName, ref, tapCmdFlags.secret, verify)
291419

292420
toApply := make([]client.Object, 0, len(sources)+1)
293421
toApply = append(toApply, ociRepo)
@@ -316,6 +444,9 @@ runs its charts in your management cluster: tap only sources you trust.`,
316444
if existing.Spec.URL != "" && existing.Spec.URL != ref.URL {
317445
return fmt.Errorf("a different repository (%s) is already tapped as %q; run 'cozypkg untap %s' before tapping %s", existing.Spec.URL, srcName, names[0], ref.URL)
318446
}
447+
// Same repository, re-tapped: carry over a verify policy or pull secret
448+
// this invocation did not set, so moving the pin never silently drops them.
449+
carryoverSourceFields(ociRepo, existing, verify, tapCmdFlags.secret)
319450
}
320451

321452
// A tapped repository keeps its own declared name. Refuse the whole tap
@@ -350,12 +481,13 @@ runs its charts in your management cluster: tap only sources you trust.`,
350481
// PackageSource removed out-of-band since the last materialization. Tapping
351482
// no longer installs anything, so a re-tap does NOT re-install an app removed
352483
// with `cozypkg del`; re-install it with `cozypkg add`. A first tap has no
353-
// such annotation, so this is a no-op then.
354-
if err := clearMaterializedRevision(ctx, k8sClient, srcName); err != nil {
484+
// such annotation, so this is a no-op then. resetTapPinState also drops the
485+
// operator's prior digest pin so the newly requested tag re-resolves.
486+
if err := resetTapPinState(ctx, k8sClient, srcName, ref.Digest != ""); err != nil {
355487
_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "warning: could not reset materialization state on OCIRepository/%s: %v\n", srcName, err)
356488
}
357489

358-
fmt.Fprintf(cmd.OutOrStdout(), "Tapped %s\n OCIRepository/%s (%s:%s)\n", fullRef, srcName, ref.URL, ref.Tag)
490+
fmt.Fprintf(cmd.OutOrStdout(), "Tapped %s\n OCIRepository/%s\n", fullRef, srcName)
359491
for _, n := range names {
360492
fmt.Fprintf(cmd.OutOrStdout(), " PackageSource/%s\n", n)
361493
}
@@ -509,6 +641,8 @@ func init() {
509641
tapCmd.Flags().StringVar(&tapCmdFlags.kubeconfig, "kubeconfig", "", "Path to kubeconfig file")
510642
tapCmd.Flags().StringVar(&tapCmdFlags.index, "index", "", "Index location for resolving a short name (local dir or oci:// ref; defaults to COZYPKG_INDEX)")
511643
tapCmd.Flags().BoolVar(&tapCmdFlags.skipValidate, "skip-validate", false, "Skip validating the artifact before tapping")
644+
tapCmd.Flags().StringVar(&tapCmdFlags.certIdentity, "certificate-identity", "", "Keyless cosign certificate identity (subject regex) to verify the artifact's signature against at pull time; requires --certificate-oidc-issuer")
645+
tapCmd.Flags().StringVar(&tapCmdFlags.certIssuer, "certificate-oidc-issuer", "", "Keyless cosign OIDC issuer (regex) to verify the artifact's signature against at pull time; requires --certificate-identity")
512646
untapCmd.Flags().StringVar(&tapCmdFlags.kubeconfig, "kubeconfig", "", "Path to kubeconfig file")
513647
untapCmd.Flags().BoolVar(&untapConfirmFlag, "yes", false, "Untap even if a Package from this source is still installed")
514648
}

0 commit comments

Comments
 (0)