auth: scope hints are keyed per host, so namespaces on the same registry share one hint bucket

[TerryHowe]

Summary

#1370 narrowed scope hints from global to per host, closing #1362. The remaining narrowing asked for in #1348 — from per host to per registry scope (host + namespace) — is not covered by that PR and is tracked here.

Scope hints today are keyed at the host but valued at the repository. scopesForHostContextKey is a string of the host, so there is one bucket per host, while the strings inside it are already repository-granular (repository:namespace1/app:pull,push, via ScopeRepository). Registry-side authorization is therefore already namespace-granular. What is host-level is the bucket.

Code references are pinned to 7f80a16.

Why the bucket granularity matters

The bucket decides two things:

1. Which hints ride along on a request. The whole bucket goes into a single token request — q.Add("scope", scope) per entry in the distribution flow, space-joined into the form for OAuth2.
2. The token cache key — strings.Join(scopes, " ") (client.go:289 and :337).

For a registry that partitions by namespace — harbor.local/namespace1 and harbor.local/namespace2 threaded through one context — that means:

• Cross-namespace disclosure. A token fetch during namespace2 work also asks for namespace1's repositories. Harbor issues a token for the subset it grants and drops the rest, so it is usually not an auth failure, but namespace1's repository names are disclosed on a request that has nothing to do with them. Same shape as auth: global scope hints are sent to every host contacted in the context #1362, narrowed to within-host.
• Cache-key churn. Every append changes the key for every subsequent request to that host, so a token cached during namespace1 work misses once namespace2 scopes land. Extra token round trips, which is the opposite of what a hint is for.
• Unbounded growth. Each AppendScopesForHost re-runs CleanScopes over the whole bucket, and DistributionTokenFetcher puts each scope in the query string, so a long-lived context spanning many namespaces heads toward URL-length limits.

In-tree this stays small — each repository method appends to a local context that dies with the call, and the widest case is two repositories on one host (blob mount appends repoRef then fromRef, registry/remote/repository.go:1197-1202). It bites the caller who threads one context across namespaces, which is exactly the oras login example.com/myspace shape #1348 is about.

Proposal

Key the scope-hint bucket on properties.Resource — the value type #1380 landed for namespace-aware credential resolution — rather than leaving this half host-only. If the credential key is namespace-aware and the hint key is not, the two halves of the auth path disagree about what identifies a resource.

func WithScopesForResource(ctx context.Context, res properties.Resource, scopes ...Scope) context.Context
func AppendScopesForResource(ctx context.Context, res properties.Resource, scopes ...Scope) context.Context
func GetScopesForResource(ctx context.Context, res properties.Resource) []Scope

The ...Scope rather than ...string assumes #1451 lands first — see Sequencing below.

Design caution

Narrowing the key means Client.Do can no longer do the exact map hit that GetScopesForHost does. It needs a longest-prefix walk, the way GetAuthConfigHierarchical already does for credentials.

The URL-parsing half of this concern has since been solved. An earlier revision of this issue said Do only has originalReq.URL and cannot split a namespace out of /v2/<name>/... because <name> may contain slashes. #1398 has since landed registry/remote/auth/resource.go, and Do already derives a properties.Resource from the request via requestResource (client.go:278), splitting the path at the rightmost endpoint separator. The lookup therefore starts from a Resource{Registry, Path}, not from a raw URL.

What remains is narrower: the derived Path is the full repository (namespace1/app) while the registered key is a namespace prefix (namespace1), and nothing in the path marks the boundary between them. So the bucket still has to be selected by prefix-matching the derived resource against the keys the caller registered, rather than by an exact map hit.

Two details for whoever implements it:

• repositoryFromPath returns "" for a path that does not address a repository (/v2/_catalog, /v2/), and deliberately degrades to "" rather than naming a bogus repository when ValidateRepository fails. The prefix walk needs a registry-level fallback for the empty-Path case, or catalog requests silently lose their hints.
• requestResource stores the canonical registry name — a request dialed at registry-1.docker.io derives docker.io. Keys registered by callers and keys derived from requests line up only because both sides are canonical. Worth an explicit test, since a regression there fails open: every lookup misses, hints silently stop working, and nothing errors.

Notes

• This is additive over what fix(auth): prevent scope hints from crossing registry hosts #1370 landed: a host-level bucket is a strict improvement over the global one, and narrowing the same key later does not undo it.
• Dependency cleared. auth: add a Resource type for a registry host optionally narrowed to a namespace #1380 landed properties.Resource, so the key type this needs now exists.

Sequencing

Land after #1451 (typed Scope, which supersedes #1363). Both change the same four exported functions, so:

• Implement against the typed signature — scopes ...Scope, not ...string. Writing this against the string API means redoing it.
• auth: make Scope a typed value instead of a string, and fix CleanScopes de-duplication (decided) #1451 consolidates the bearer cache key into a single helper. This change alters what goes into that key, which would otherwise have to be edited in two places (client.go:289 and :337).
• Both are breaking changes to the same call sites, and v3.0.0-rc.1 shipped on 2026-09-03. Getting both in before v3.0.0 GA avoids making callers migrate the same functions twice across the GA line.

Related

• Add RegistryScope to support authenticating against a namespace within a registry #1348 — parent, now closed and split into smaller issues (split map).
• auth: add a Resource type for a registry host optionally narrowed to a namespace #1380 — the Resource value type used as the key here. Closed, landed.
• fix(auth): prevent scope hints from crossing registry hosts #1370 / auth: global scope hints are sent to every host contacted in the context #1362 — the host-level narrowing this follows on from.
• auth: make Scope a typed value instead of a string, and fix CleanScopes de-duplication (decided) #1451 — typed Scope instead of a string; supersedes auth: make Scope a typed value instead of a string, and fix CleanScopes de-duplication #1363. Sequence this issue after it.

Originally raised as this comment on #1348.

[TerryHowe]

For context: #1348 has been closed and split into smaller issues, and this is one of them. The split map is in this comment.

This depends on #1380 (the Resource value type) for the key, and reads more cleanly after #1363.

[TerryHowe]

Refreshed the issue body. What changed:

The Design caution was half wrong. It said Do only has originalReq.URL and cannot split a namespace out of /v2/<name>/.... #1398 has since landed registry/remote/auth/resource.go, and Do already derives a properties.Resource from the request via requestResource. The conclusion still holds — a longest-prefix walk is still required — but for a narrower reason: the derived path is the full repository while the registered key is a namespace prefix, and nothing marks the boundary. The walk is over a Resource, not over raw URL paths, which makes it meaningfully less unpleasant than the old text implied.

Two implementation details added while I was in there: the walk needs a registry-level fallback for repositoryFromPath returning "" (catalog requests would otherwise lose their hints), and requestResource canonicalizes registry-1.docker.io to docker.io, so registered and derived keys agree only because both sides are canonical. That one fails open if it regresses — every lookup misses, hints stop working, nothing errors — so it wants an explicit test.

Dependency cleared. My comment above says this depends on #1380 for the key type. #1380 is closed and landed, so properties.Resource exists and this is unblocked.

Sequencing against #1451. #1363 is closed, superseded by #1451, which carries the same typed-Scope work with the API questions decided. Both issues change the same four exported functions, so the proposal here now shows scopes ...Scope — implementing this against the string API means redoing it. #1451 also consolidates the bearer cache key into one helper, which is where this change would otherwise land twice. Both are breaking, so they want to be on the same side of the GA line.

Line references are now permalinks pinned to 7f80a16. client.go (289/337, was 292/340), repository.go (1197-1202, was 1179-1184) and configfile.go (173, was 184) had drifted; the scope.go and token.go refs were still accurate.