feat(client)!: add Docker Hub auth sub-client

[Benehiko]

What

Adds client/dockerhub: a typed sub-client for reading Docker Hub authentication state (access tokens and account profiles) from the secrets engine.

Why

Fetching a Hub token today means knowing the realm layout (docker/auth/hub/**, docker/auth/metadata/hub/**) and the raw JSON payload format. This PR hides both behind a small typed API.

API

client.Client gains an accessor (kubernetes-clientset style); dockerhub.New wires the same sub-client over any bare secrets.Resolver:

c, _ := client.New()
hub := c.HubAuth() // or c.HubAuth(dockerhub.Staging())

session, err := hub.GetDefaultSession(ctx)
fmt.Println(session.AccessToken, session.Claims.Username)

Method	Returns
GetDefaultSession(ctx)	session of the default signed-in account
GetSession(ctx, username)	session of a specific account
GetDefaultProfile(ctx)	profile of the default account
ListProfiles(ctx)	profiles of all signed-in accounts

A UserSession carries the raw JWT (AccessToken) plus decoded Claims — typed NumericDate and Audience, no JWT library dependency.

Errors: ErrNoSession (no stored credential) and ErrNoDefaultProfile (no default account set). The latter wraps the former, so callers that only care about having a usable session check one sentinel.

Safety

• GetSession rejects usernames containing / or wildcards, so a username can only ever address one account entry.
• GetDefaultSession validates that the stored user_id names exactly one account entry inside the accounts realm (docker/auth/hub/*), so a tampered profile cannot redirect the lookup to another secret.
• Staging and production realms are pinned per sub-client: ids from one never resolve on the other.

Also in this PR

• README: new "How to fetch a Docker Hub access token" guide.
• Realm godoc for docker/auth/metadata/hub/** corrected: it holds one profile entry per signed-in account plus a default entry duplicating the default account's profile (previously described as a single default-user pointer).

Breaking: the Client interface gains a HubAuth method — implementations must add it.

🤖 Generated with Claude Code

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

This PR introduces a well-structured typed sub-client for Docker Hub authentication. The security design (realm pinning, username validation, default-session guard) is sound overall. One correctness bug was confirmed in the nil-envelope-ID path of ListProfiles, and a best-effort error-suppression behaviour is undocumented.

[docker-agent]

[MEDIUM] Default entry included in results when secrets engine omits envelope IDs

The guard at line 250 uses if envelope.ID != nil && c.cfg.defaultEntry.Match(envelope.ID) — when envelope.ID is nil the entire condition is false and the default entry is not skipped. It falls through to parseProfile and can be appended to the returned slice.

The seen-map deduplication masks this in the existing test (skips the default entry without envelope IDs) because default and alice share the same UserID — whichever is iterated first is kept, the other is dropped. If the two entries ever hold different data (e.g. the default profile was updated but the per-account entry hasn't been flushed yet, or any future provider populates them differently), a caller of ListProfiles may receive the default entry as a regular profile instead of the canonical per-account one.

Suggested fix:

// Skip the default entry: either we have an ID and it matches, or the
// engine omits IDs entirely and we fall back to matching by key name.
if envelope.ID == nil || c.cfg.defaultEntry.Match(envelope.ID) {
    continue
}

[docker-agent]

[LOW] Parse errors silently discarded when at least one profile succeeds

ListProfiles returns errors only when zero profiles parsed successfully (line 264: if len(profiles) == 0 && len(errs) > 0). If 9 out of 10 stored profiles have a corrupt payload, the caller receives 1 profile and a nil error — with no indication that any accounts are missing.

The test skips undecodable entries explicitly asserts require.NoError in this scenario, so the best-effort behaviour is deliberate. However, the API contract is not documented, which could mislead callers who need to know whether the returned list is complete.

Consider adding a note to the ListProfiles godoc — e.g. "Profiles that cannot be decoded are silently skipped; the error is returned only if no profiles could be decoded at all." — so callers that need reliable completeness can decide whether to handle this at their layer.