Skip to content

Commit 5747f94

Browse files
committed
docs(marketplace): document digest pinning and verify on tap
Update the tap command help and the community-index README for the new behaviour: digest references, the automatic tag-to-digest pin, the --certificate-identity / --certificate-oidc-issuer pull-time verify flags, and the optional index entry digest. Extend the generated openapi definitions and model-name helper for the new TapVerify type (code generation is otherwise run in CI). Assisted-by: LLM Signed-off-by: IvanHunters <[email protected]>
1 parent c59ced0 commit 5747f94

4 files changed

Lines changed: 64 additions & 9 deletions

File tree

‎cmd/cozypkg/cmd/tap.go‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -307,12 +307,19 @@ With --secret the OCIRepository is given a pull-credential secretRef (the
307307
admin pre-creates the Secret in cozy-system), so a private repository taps in
308308
one command.
309309
310-
Trust: tap validates the artifact's structure but does NOT verify its cosign
311-
signature. Signature verification is the community index's job at publication
312-
time ('cozypkg validate --require-signature' in the index CI gate, pinned to
313-
the entry's recorded identity), and can additionally be enforced at pull time
314-
via Flux OCIRepository verification. Tapping a third-party repository runs its
315-
charts in your management cluster: tap only sources you trust.`,
310+
Pinning: a tapped repository does not follow a moving tag. A reference given by
311+
digest (oci://host/org/repo@sha256:...) is pinned to that digest immediately; a
312+
tag reference is pinned to the digest it currently resolves to as soon as the
313+
source materializes, with the tag kept informational. Moving the tag upstream
314+
changes nothing in the cluster; tap the repository again to move the pin.
315+
316+
Trust: tap validates the artifact's structure. Keyless signature verification at
317+
pull time is enabled with --certificate-identity and --certificate-oidc-issuer,
318+
which set a Flux cosign verify policy on the source so content is pulled only
319+
when signed by that identity. Signature verification at publication time is the
320+
community index's job ('cozypkg validate --require-signature' in the index CI
321+
gate, pinned to the entry's recorded identity). Tapping a third-party repository
322+
runs its charts in your management cluster: tap only sources you trust.`,
316323
Args: cobra.ExactArgs(1),
317324
RunE: func(cmd *cobra.Command, args []string) error {
318325
ctx := context.Background()

‎hack/packages-index/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Each file under `entries/` is a single record (see `entries/example.foo.yaml`):
2020
name: foo.bar
2121
ociRef: oci://ghcr.io/foo/bar
2222
version: v1.2.3
23+
digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
2324
description: A SQL database operator
2425
maintainer: Foo <[email protected]>
2526
homepage: https://example.com/foo
@@ -31,15 +32,17 @@ signing:
3132
issuer: https://token.actions.githubusercontent.com
3233
```
3334
35+
`digest` is optional but recommended: when set to the `sha256:<hex>` the gate verified, tapping the entry's short name pins that exact content instead of following the `version` tag, so a later retag of the same version cannot change what installs. The gate records it from the artifact it just verified, and `version` is kept informational alongside it.
36+
3437
## Two-lane merge policy
3538

3639
Following krew-index, submissions take one of two lanes:
3740

38-
- **Owner version bump.** A change that only updates an existing entry's `version` or description, leaving `ociRef` and `signing` untouched, auto-merges once the new artifact validates and is signed by the entry's **recorded** cosign identity. This keeps the routine "new release of a listed package" path fast.
41+
- **Owner version bump.** A change that only updates an existing entry's `version`, `digest`, or description, leaving `ociRef` and `signing` untouched, auto-merges once the new artifact validates and is signed by the entry's **recorded** cosign identity. This keeps the routine "new release of a listed package" path fast.
3942
- **New entry, or a change to `ociRef`, `maintainer`, or `signing`.** These are the security-relevant edits and require maintainer review before merge.
4043

4144
Cosign verification is **mandatory** on the gate for both lanes: the trust anchor is the recorded signing identity, so a bump fails if the new artifact is not signed by the originally approved identity.
4245

4346
## Trust model
4447

45-
Signature verification happens here, at publication time, not at tap time. `cozypkg tap` and the dashboard connect flow validate an artifact's structure but do not verify its cosign signature: a cluster that taps a listed repository trusts that this index already verified it. The verification points are this CI gate (which pins each release to the entry's recorded identity) and, optionally, Flux `OCIRepository` verification at pull time. Tapping a third-party repository runs its charts in the management cluster, so operators should tap only sources they trust or that appear in a curated index like this one.
48+
Signature verification happens here, at publication time, not at tap time. `cozypkg tap` and the dashboard connect flow validate an artifact's structure; they do not verify a cosign signature unless asked (with `--certificate-identity` / `--certificate-oidc-issuer`, which set a Flux pull-time verify policy). A cluster that taps a listed repository otherwise trusts that this index already verified it. The verification point is this CI gate, which pins each release to the entry's recorded identity. Independently of signing, a tapped repository is pinned to a digest and does not follow a moved tag: a `digest` recorded on the entry pins the exact content the gate verified, and a tag-only tap is pinned to the digest it first resolves to. Tapping a third-party repository runs its charts in the management cluster, so operators should tap only sources they trust or that appear in a curated index like this one.

‎pkg/apis/core/v1alpha1/model_name.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,7 @@ func (in TapSource) OpenAPIModelName() string {
118118
func (in TapPackage) OpenAPIModelName() string {
119119
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TapPackage"
120120
}
121+
122+
func (in TapVerify) OpenAPIModelName() string {
123+
return "com.github.cozystack.cozystack.pkg.apis.core.v1alpha1.TapVerify"
124+
}

‎pkg/generated/openapi/zz_generated.openapi.go‎

Lines changed: 42 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)