feat(auth/gcp): add GCP credential provider

[wolo-lab]

Problem

auth/gcp has the credentials-service REST client (#1149) but no auth.CredentialProvider that resolves the acting user's credential from the invocation context. Without it there is no way to wire per-user GCP credentials (Agent Identity / IAM Connector) into a tool call — adk-python has this via its GCP auth provider.

Resolving a credential per end user also needs a way to recover which user, from code that holds only a context.Context. A tool's outbound request reaches an http.RoundTripper several layers below the tool call, past jsonrpc2 and net/http wrapping, with the typed ADK context long since erased.

Summary

• Add gcp.NewProvider(ctx, gcp.ProviderConfig), returning an auth.CredentialProvider that resolves a per-user credential through the REST client and maps it to an auth.Credential. The acting user is read from the ADK context at resolve time, so the provider is long-lived and shared, and never needs per-user configuration. ctx roots the default client that is built lazily when ProviderConfig.Client is nil — values only, cancellation is not honored, because that client outlives any one request.
• Add agent.Identity and agent.IdentityFromContext(ctx) (Identity, bool). ADK contexts answer a private key held in internal/adkcontext, a module-internal leaf package shared by agent and internal/context to break the import cycle. Code outside the module cannot name that key, so it cannot mint an identity onto a context that has none. It can still read or rewrite the agent.Identity a wrapper passes through, so the identity is trusted only as far as every wrapper in the chain is, and the doc says so.
• Three context types answer the key, and they agree. The two that own a session — internal/context.InvocationContext and agent.invocationContext — answer for themselves and never delegate: a nested invocation with no session of its own reports no identity rather than the enclosing invocation's user, whose credential would otherwise be minted for a call they never made. agent.commonContext owns no session, so it asks the invocation it wraps and takes that answer as final. That keeps a tool or callback context working, since theirs return a nil session by design and delegate the key downwards themselves.
• The identity read recovers rather than nil-testing. session.Session is a public interface of six accessors, so a struct value implements it naturally, a typed-nil pointer survives an interface-nil check, and a session wrapping a nil session (the shape llmagent.newWrappedSession produces for a nil original) panics in the accessor. This runs inside http.RoundTripper, where net/http does not recover, so a session that cannot answer costs the identity and not the process, and the credential path fails closed.
• The lazy default client bounds its waiters, not its attempt. google.FindDefaultCredentials reads the credentials file with os.ReadFile and probes with the context-free metadata.OnGCE(), so no context can interrupt it. Each caller waits on the earlier of its own context and 30s. A failed attempt is not cached and the next call retries. A hung one is kept rather than abandoned — abandoning it starts a fresh lookup every 30s, each parked in a syscall pinning an OS thread — and if it eventually lands, its client is published to everyone after it.
• NewProvider validates at wiring time what would otherwise fail on every request from inside a transport: the resource name must be one of the two shapes Client routes on, and a Client that did not come from NewClient is rejected. The shape check is stricter than Client and than adk-python, both of which send any non-connector name to Agent Identity, and ProviderScheme.Name labels it as such.
• New sentinels: gcp.ErrNoActingUser (no ADK identity on the context, or an invocation whose session carries no user — the two are distinguishable by message) and gcp.ErrClientUnavailable (the default client was not ready in time). Existing sentinels, *APIError and *auth.ConsentRequiredError all stay reachable with errors.Is/errors.As through the provider's wrap.
• A provider error names the resource and nothing else. It becomes the tool's error, which is fed back to the model and persisted as a session event, and every identifier available at that point is caller-supplied — session.UserID is commonly an email, and the session id arrives unvalidated from the request path. This is a deliberate divergence from adk-python, which names the user.

Behavior change to existing code

auth.ConsentRequiredError.Error() no longer prints the authorization URI, which stays on the AuthURI field for consumers to read. The URI carries the state and the consent nonce that bind the credential, and this error reaches the model and the session store by the path above. apidiff reports the change as additive because no signature moved — the message text is not part of what it compares. Nothing in the tree matches on that message.

Requirements this puts on the transport

Neither can be enforced from this package, and both are stated on NewProvider.

• Every authenticated request must descend from the invoking user's context. A transport that shares one connection across invocations does not qualify, mcptoolset included: its per-call POSTs are per-user, but the MCP session and the standalone server-to-client stream are opened on the context of whichever user connected first and stay bound to it.
• The transport must not follow a cross-host redirect. net/http strips Authorization above the RoundTripper, so auth.Transport re-resolves and re-applies the end user's credential to the redirect target. The ADC-backed client NewClient builds for itself already refuses redirects for the same reason.

Both live in packages this PR does not touch and will get their own issues.

[karolpiotrowicz]

The shape of the change is good: the leaf package to break the agent ↔ internal/context cycle is a clean way to solve it, the Value overrides delegate correctly for every other key, and the defensive copy of Scopes does what its comment claims. Two things need fixing before this lands, and there's a short list of smaller items below.

The default path doesn't work. resolveClient builds the ADC-backed client on a context it cancels one line later, and the token source keeps that context — so with ProviderConfig.Client == nil (the documented default) every credential retrieval fails with context canceled, permanently, because the broken client is then cached. Details inline on auth/gcp/provider.go. It reproduces on authorized_user (the gcloud auth application-default login path), external_account (workload identity federation) and impersonated_service_account; it happens to survive on a service-account JSON key and on GCE/GKE metadata, because those two token sources don't bind the request to the construction context. This is invisible today because resolveClient's lazy-init block has no test coverage.

Two tests don't test what they're named for. Deleting the identity guard in Credential entirely leaves all three provider tests passing, and adding a cross-user credential cache — which would break the provider's headline per-user isolation property — also leaves them all passing. Both are noted inline with the mutations that demonstrate it.

Cross-user credential scope. Worth thinking through before this gets wired up: with a per-user provider behind an auth.Transport, per-request calls are correctly scoped, but a transport that keeps a long-lived shared connection is not. Inline on the doc comment that recommends that wiring.

Smaller items, grouped so they don't clutter the diff:

• auth/gcp/provider.go:88-91 — errors from resolveClient and RetrieveCredential are returned bare, so a process with several providers wired in gives an operator no way to tell which resource or which user failed. Wrapping with %w keeps errors.Is/errors.As working for the sentinels and the consent error.
• auth/gcp/provider.go:58 — this is the only error-returning constructor among the providers in auth (StaticToken, APIKey, TokenSourceProvider, ADC, ServiceAccount all return a bare CredentialProvider), and it validates only an empty Name, while RetrieveCredential rejects a much wider class on every request. Either validate fully here or drop the error and match the siblings. Relatedly, returning the interface rather than a concrete *Provider freezes the callable surface — worth deciding before the API is public.
• auth/gcp/provider.go:32 — Scheme is a slightly overloaded name in this package: mapCredential already uses scheme for the HTTP auth scheme, and the endpoint fields document "scheme+host". ProviderScheme would read unambiguously and tracks the reference implementation's GcpAuthProviderScheme.
• auth/gcp/provider.go:46-50 — on the nil-Client path there's no way to point at a non-production endpoint, since :129 hardcodes NewClient(dctx, nil). Building a Client and passing it does work, so this is only about the convenience path.
• auth/gcp/provider.go:82 — Identity.UserID is supplied by the embedding server and isn't authenticated anywhere in the framework. That was fine when it was a storage partition key; this change makes it decide whose credential gets minted. Worth stating that trust requirement explicitly in the doc.
• auth/gcp/provider.go:91 — a failing retrieval's error becomes the tool's error and is fed back to the model and persisted in the session, which carries the consent URI and part of the service's response body along with it. Consider keeping the URI on the struct field and out of Error().

Two questions rather than assertions:

• agent.Identity carries {UserID, AppName, SessionID} but not the current function-call id. The reference implementation uses that id for its consent anti-loop check (it asks whether consent for this tool call already completed before re-prompting). Adding the field later is a compatible change, so this isn't urgent — but is leaving it out now a deliberate call?
• Is per-request credential retrieval the intended cost model? Since auth.Transport resolves on every outgoing request and nothing here caches, each request costs a full retrieval, and a pending response costs up to PollTimeout (10s by default) inside a RoundTripper. The service response carries no expiry, so caching may well be the wrong answer — but it seems worth a note either way.

[karolpiotrowicz]

This doc link doesn't resolve — it renders as the literal text [agent.IdentityFromContext], brackets and all, because Go's doc tooling only resolves a [pkg.Sym] link for packages the file actually imports, and nothing in package auth imports .../agent. (The identical text in auth/gcp/provider.go:55 does render as a link, since that package imports agent.)

Adding the import just for a doc link would create a real layering dependency, so naming the package in prose is probably the cheaper fix.

[karolpiotrowicz]

The routing through the ADK context is the right shape, and the parts that carry the security weight hold up: the identity is re-read from the calling context on every request so a shared provider never serves one user's credential to another, Scheme.Scopes reaches the wire unmodified, the defensive copy is real, and no error path carries a token. Two areas need work before this lands.

Value can panic, and the guard added to prevent that is one of the causes

hasSession ends in return s != nil && !reflect.ValueOf(s).IsNil(). reflect.Value.IsNil is only defined for chan, func, interface, map, pointer, slice and unsafe pointer — for anything else it panics. session.Session is a public interface of six read-only accessors, so a struct value is a natural way to implement it, and s != nil is true for a struct, so the short-circuit does not help.

Calling hasSession directly with each receiver shape:

pointer receiver     -> true
typed-nil pointer    -> false
nil                  -> false
struct value         -> panic: reflect: call of reflect.Value.IsNil on struct Value

The guard does what it was written for and panics on a different legal input.

Three separate shapes reach a panic, and they need to be considered together because they do not share a fix:

• A struct-value session panics in reflect.IsNil, as above.
• A typed-nil session is correctly rejected by hasSession, and then Value falls through to c.Context.Value(key). For a Promoted context that embedded context is the parent *InvocationContext, whose Value guards with a plain c.params.Session != nil and then dereferences. The reflect guard is undone by its own delegation.
• A non-nil pointer wrapping a nil inner session passes both checks — the pointer is genuinely non-nil — and both then call UserID().

That third shape is the constraint on any fix: because the accessors are arbitrary third-party code, no nil test can make Value panic-free. A kind-aware IsNil closes the first two and leaves the third. Snapshotting the Identity once at NewInvocationContext time would close all three and move the accessor calls off the per-request path, at the cost of not tracking a session mutated mid-invocation. A recover in the identity lookup also works.

Worth fixing even though no current deployment hits it. Every production session.Session is a pointer type, and the four value-typed implementations in the tree are all fakes — including TestSession, which is in a non-_test.go file but is imported only from tests. What makes it worth blocking on is where it lands rather than how often: auth.Transport resolves a credential per outbound request, so this executes inside http.RoundTripper on the caller's goroutine, where net/http does not recover. It is reachable by correct third-party code against a public interface, and both Value doc comments currently promise the opposite — agent/common_context.go says "Value never panics" and internal/context/invocation_context.go says "never panicking".

The two Value implementations should also agree. For a typed-nil session that does not dereference, one returns ok=false and the other returns ok=true with an empty Identity. One shared helper for "is there a usable session" would remove the divergence and the duplicated logic.

A hung ADC lookup wedges the provider for the process lifetime

resolveClient bounds each waiter but nothing bounds the init itself. context.WithoutCancel strips the deadline without adding one, and singleflight holds the "client" key until the function returns. If FindDefaultCredentials blocks — a stalled NFS or gcsfuse mount, an ADC path that is a FIFO or a device, a hung resolver inside OnGCE — the key is never released and p.client is never set, so every later call attaches to the dead flight and can only burn its own deadline.

With the ADC path a FIFO, then the environment repaired with a valid credentials file before the second caller arrives:

caller 1, 300ms budget                     -> context deadline exceeded after 301ms
caller 2, healthy environment, 2s budget   -> context deadline exceeded after 2.001s

The doc comment's "a failed init is not cached; the next call retries" holds for a failed init but not a hung one. auth/providers.go already solves this for the sibling lazy path — initTimeout = 30 * time.Second, with the comment "bounds a hung init so it fails and is retried, not wedged forever". Since FindDefaultCredentials ignores cancellation, the bound has to retire the attempt rather than just pass a bounded context, which is what lazyTokenSource does.

The shared client inherits whichever caller won the cold-start race

Same function: NewClient(context.WithoutCancel(ctx), nil). WithoutCancel strips cancellation but keeps values, so the process-lifetime client is parameterised by one arbitrary request. NewClient hands that context to oauth2.NewClient, which reads oauth2.HTTPClient off it, and to FindDefaultCredentials, whose token source retains it for every later refresh.

With Alice's context carrying an instrumented oauth2.HTTPClient and Bob's context plain, Alice's transport carried both the ADC token mint and Bob's credential retrieval. It also pins that first invocation's whole context graph — session, events, agent, artifacts — for the life of the process, and that retained context still answers the identity key with Alice's Identity.

Nothing about a shared client needs a per-request value. Rooting it at context.Background() removes both effects. If some ambient value really is needed, taking it explicitly in ProviderConfig would at least make it deterministic.

Smaller things

• auth/gcp/doc.go now contradicts the package. Lines 27-29 say "This package holds only the transport-level client. The auth.CredentialProvider that resolves the acting user from the invocation context is a separate, higher layer." This PR puts that provider here, and that paragraph is the first thing go doc auth/gcp prints.
• The fail-closed paths have no tests. Every error branch in resolveClient is uncovered, including ADC discovery failing, and so is the empty-UserID guard. They behave correctly today, but deleting the UserID guard leaves the suite green while changing the error callers see from ErrNoActingUser to a bare one from RetrieveCredential. The same is true of the reflect branch in hasSession — removing it keeps everything green, which is why the struct case shipped. Worth a table over {pointer, typed-nil, struct value, nil, wrapper-over-nil}, since that table would have caught all three panics.
• NewProvider validates Name only for emptiness. resourceNameRE and the .. check live in RetrieveCredential, so a malformed resource name fails on every request inside a RoundTripper instead of once at wiring time. Both are in package gcp, so validating in the constructor costs nothing. A misspelled collection (authProvidrs) is the awkward case — it passes the charset filter and silently routes to Agent Identity.
• Errors come back unwrapped. resolveClient returns r.Err and ctx.Err() bare, and Credential passes resolveClient's error straight through, so a DeadlineExceeded out of Credential gives no hint whether it came from client init or the credential fetch.
• UserID is now an ambient assertion. Previously a caller passed it explicitly to RetrieveCredential. Now any request whose context descends from an invocation is signed as that session's user, with no call site naming them. Authorization is the service's job, but the docs on NewProvider and agent.Identity should say that binding session.UserID() to an authenticated principal is a precondition.
• TestResolveClientHonorsCallerDeadline asserts elapsed > time.Second against a 50ms deadline. A regression to a 900ms floor would pass.
• IdentityFromContext can return ok=true with an empty UserID, which the doc does not mention. The provider handles it, the next caller may not.

All line references above are pinned to 458290d41b04b4a140e683ad88390bd102a76265.