Draft: docs(specs): scope the S32 referrers fallback to its actual clients

What this does

Scopes the referrers tag-schema fallback to the OCI clients that actually take it. The spec stated it unconditionally in four places. The error code the route returns is what decides whether a given client falls back at all.

The measurement

  • crane, and anything on go-containerregistry, reads no error code at all. It falls back on a 404, 400, or 406, or on a 200 whose Content-Type is not an OCI index, and returns any other status as an error. fetchReferrers calls transport.CheckError(resp, 200, 404, 400, 406) first and CheckError errors on anything outside that set, so a 503 reaches no fallback at all (pkg/v1/remote/referrers.go and pkg/v1/remote/transport/error.go, v0.20.6).
  • oras parses the body and returns the error when the code is NAME_UNKNOWN. Its fallback has one trigger, errdef.ErrUnsupported, which a 404 produces only under some other code (registry/remote/repository.go, oras-go v2.5.0 and v2.6.0).
  • Notation inherits that through oras-go, and reaches it only for a target implementing registry.ReferrerLister — true for a network registry, false for a local oci.Store (notation-go v1.3.2, which pins oras-go v2.5.0).

An earlier revision of this branch stated the crane rule as "any response that is not an OCI index". That is wrong, and the conclusion for this route surviving is what made it read as correct: 404 is in the admitted set, so crane does fall back here. The rule is what the paragraph exists to carry, and the broad form told a reader that a 503 from a virtual repository also degrades gracefully.

The four sites

Section Change
### Referrers Carries the split and its measurement, plus what it costs the erroring half: referrers discovery fails outright there rather than degrading
## Security Considerations Keeps the substitution exposure and bounds it to the falling-back clients
## Open Questions Carries the same bound, because the case for a preventive control rests partly on the fallback governing trust metadata
## Resolutions Same unqualified claim, corrected in passing

The ## Follow-ups entry is corrected too: it described the ADR-009 amendment as annotating two routes, and four route lines carry it.

Two judgments a reviewer should check

The exposure narrows; it is not mitigated. Nothing in the arrangement selects which client pulls, and go-containerregistry sits under a wide range of CI tooling. The text says a control chosen for this surface still has to assume the exposed half is in use, rather than letting "narrower" read as "less urgent".

The other half is a functional limit, not a second exposure. oras and Notation get an error, so a verification that cannot fetch referrers fails closed. That costs function rather than safety, and ### Referrers previously claimed the opposite — "degrades instead of failing outright" — which is false for those clients.

Why this is Draft

## Security Considerations and the #792 GA-blocking gate's rationale both change here, so this wants a named reviewer rather than the roulette. Undraft once one is assigned.

Where this came from

The review of the ADR-009 amendment (gitlab-com/content-sites/handbook!20929 (merged)), where the same qualification now lands in the ADR. The plan's ADR-009 entry carries the matching fix in !2063 (merged).

Edited by Radamanthus Batnag

Merge request reports

Loading
Loading