Define source and target registry policies for COSIGN_REPOSITORY

[reneleonhardt]

Description

COSIGN_REPOSITORY redirects artifacts, but Cosign uses one go-containerregistry remote-option policy for source and target. Registry-aware keychains resolve lazily per registry; fixed credentials, mTLS, CA/server-name, insecure/HTTP settings, and reused clients cannot be configured independently.

For a genuine redirect, source-policy reuse can authenticate to the wrong registry or send source-bound material to the target. Opaque WithRemoteOptions and CLI RegistryClientOpts have the same ambiguity: Cosign cannot inspect functional options for credentials, mTLS, insecure transport, or reused clients.

Design only. No implementation proposal until maintainers choose the public contract.

Recommended contract

Separate source and target roles whenever canonical repository identities differ. Exact canonical identity preserves behavior. Same-host/different-repository remains a boundary: tokens and clients can be repository-scoped. DNS aliases, mirrors, redirects, and unproven aliases do not establish policy equivalence.

For a genuine redirect:

• CLI constructs lazy keychains per role and passes complete target options.
• Target transport replaces, never augments, source transport. With variadic WithTargetRemoteOptions(...remote.Option), zero options explicitly select GGCR default/anonymous behavior; absence is distinct. Use another API to select Cosign keychain defaults.
• Target name policy is separate: parse COSIGN_REPOSITORY, HTTP/insecure name.Option, and identity independently from TLS CA, mTLS, server name, and transport options.
• Never copy fixed credentials, mTLS, TLS/CA/server-name/insecure settings, or clients from source to target.
• Opaque/custom source options without target policy fail before network. Authentication can still fail later through expiry or network policy.
• Append context only to cloned role-specific slices.

Reuse of opaque source options remains a possible, explicitly accepted compatibility trade-off.

Identity and policy decisions

Please decide:

1. Define identity normalization: case, namespace, port, scheme, and target name.Insecure.
2. Define allowed canonical aliases; specify ports, mirrors, redirects, DNS/CNAME aliases, and repository-scoped bearer tokens.
3. Choose fail-closed or compatibility reuse for opaque source remote.Option values.
4. Define target-policy API semantics and precedence among explicit auth, keychains, RegistryClientOpts, clients, and TLS options.
5. Choose a secret-safe CLI input. Reuse or extend add ability to use json authfile for private registry login #4123; never add secrets to argv.

Required source/target ledger

Audit every mixed operation; never infer role only from current reference:

Surface	Source role	Target role	Required treatment
SignedImage, SignedImageIndex, ResolveDigest	Subject manifest/digest reads	None	Source-only compatibility.
Legacy signatures, attestations, attachments	Subject resolution where needed	Artifact tag reads/writes	Separate target policy.
OCI referrers and bundles	Subject HEAD/digest reads	Referrer, layer, config, manifest, and bundle reads/writes	Preserve the role through recursive constructors.
WriteSignaturesExperimentalOCI, WriteReferrer, attestation writers	Subject HEAD	Artifact publication	Source subject, target publication.
WriteSignedImageIndexImages / cosign load	Image/index and earlier command-defined objects	Redirected artifact metadata	Model each commit point; see #5035 for transaction semantics.
sign, attest, attach, verify	Subject reads	Artifact reads/writes	Two-registry coverage.
clean	Subject/digest lookup when applicable	Artifact reads and deletes	Target authorization and destructive-operation coverage.
download, save, tree	Subject reads	Signature, attestation, attachment, and bundle fetches	Preserve target auth failures.
Direct GGCR SBOM attachment	Subject resolution where required	Redirected SBOM write	Separate target transport and direct-GGCR coverage.
copy	Source subject and redirected signature/attestation/SBOM reads	Destination subject and artifact writes	Model four roles explicitly: source subject, redirected artifact source, destination subject, destination artifact. Target-policy credentials must never become destination-write credentials; decide a separate destination policy or follow-up.
OriginalOptions and recursive readers	Original source role	Carried target role	Preserve role state explicitly.

Error and compatibility contract

Only proven not-found, unsupported-referrers, or non-Sigstore artifacts may fall back or be skipped. Authentication/authorization, cancellation, timeout, TLS, transport, and malformed claimed-artifact errors retain their cause; never recast them as absence or successful legacy fallback.

Required tests use two or more authenticated or request-recording registries and cover:

• no override and exact canonical same-repository compatibility;
• same-host/different-repository and different-registry isolation;
• default, Kubernetes, custom, and helper-backed keychains;
• opaque/custom source options with and without an explicit target policy, failing before network where required;
• source mTLS, CA/server-name, insecure/HTTP, and reused-client non-reuse;
• aliases, ports, mirrors, redirects, and repository-scoped tokens according to the chosen identity contract;
• legacy and OCI referrers, attachments, bundles, index publication, clean, download, save, tree, load, and recursive options;
• copy: three policies or scoped repositories across source-subject reads, redirected-metadata reads, destination checks, and destination writes; prove no credential/client crosses and preserve 401/403 causes;
• target 401/403, canceled context, TLS, transport, and non-Sigstore-referrer failures with errors.Is/errors.As assertions;
• secret-safe diagnostics and input-slice immutability.

Scope and related work

Closed #4464 covered v3 artifact placement, not separate transport policy.

Open #4123 proposes JSON authfile support; it is a candidate input. This issue defines source/target roles any CLI mechanism must honor.

Open #5035 covers publication and rollback semantics. Target routing does not make publication transactional.

Target outcome: additive, compile-compatible library seam. Existing opaque options plus a genuine redirect need an explicit runtime decision: fail-closed with migration/tests, or reuse with security acceptance. CLI integration follows separately if needed.

Observed against upstream/main 83d9ec8f4bdb25d680c2331528503cd85888868f.

Version

v3.0.0-20260731151431-83d9ec8f4bdb go1.26.5 darwin/arm64