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 ongo-containerregistry, reads no error code at all. It falls back on a404,400, or406, or on a200whoseContent-Typeis not an OCI index, and returns any other status as an error.fetchReferrerscallstransport.CheckError(resp, 200, 404, 400, 406)first andCheckErrorerrors on anything outside that set, so a503reaches no fallback at all (pkg/v1/remote/referrers.goandpkg/v1/remote/transport/error.go, v0.20.6).orasparses the body and returns the error when the code isNAME_UNKNOWN. Its fallback has one trigger,errdef.ErrUnsupported, which a404produces only under some other code (registry/remote/repository.go,oras-gov2.5.0 and v2.6.0).- Notation inherits that through
oras-go, and reaches it only for a target implementingregistry.ReferrerLister— true for a network registry, false for a localoci.Store(notation-gov1.3.2, which pinsoras-gov2.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).