feat: support full-format identity tokens on GCE

[SNO7E-G]

Fixes #526.

On GCE/Cloud Run, the identity token returned by the metadata server omits the full payload (for example, the authorized party's email) unless format=full is requested. The Python auth library already does this; this brings PHP in line.

Adds an optional, backward-compatible $idTokenFormat argument to the GCECredentials constructor. When a target audience is set, passing 'full' appends &format=full to the metadata identity request:

use Google\Auth\Credentials\GCECredentials;
$creds = new GCECredentials(
     targetAudience: 'https://my-service.run.app',
     idTokenFormat: 'full',
 );

The value is validated to standard or full. Existing callers are unaffected (the default preserves the current request). Scoped to GCECredentials; exposing the option through ApplicationDefaultCredentials::getIdTokenCredentials is a natural follow-up kept out of this PR to keep it to one subject.

Unit tests cover the appended query string and the validation error.

[bshaffer]

This works, but it's interesting because all our auth libraries other than Python (Go, NodeJS, C#, Java, Ruby, Rust, and C++) do NOT support this, and instead align with the PHP auth library's current behavior. And even Python doesn't support this, it just has format=full hardcoded (which I believe is worse).

Could you tell me the use-case that requires this? Are you getting the ID token with Credentials::getLastReceivedToken?

Here's a way this can be done with our library without having to implement this parameter:

$gce = new GCECredentials(targetAudience: 'https://my-service.run.app');
$defaultHandler = HttpHandlerFactory::build();

$customHttpHandler = function (RequestInterface $request) use ($defaultHandler): ResponseInterface {
    $uri = $request->getUri();
    
    // Append format=full to the existing query string for identity token requests
    if (strpos($uri->getPath(), '/identity') !== false) {
        $query = $uri->getQuery();
        $uri = $uri->withQuery($query . ($query ? '&' : '') . 'format=full');
        $request = $request->withUri($uri);
    }
    
    // Pass the rewritten request to the standard HTTP transport handler
    return $defaultHandler($request);
};

$tokenData = $gce->fetchAuthToken($customHttpHandler);
$fullJwt = $tokenData['id_token']; // Contained full payload (email, project, zone, etc.)

[SNO7E-G]

Good question @bshaffer — I went and checked the other libraries before answering, and the picture is a bit different from what we both might have assumed:

• Node.js hardcodes format=full on the identity request:(https://github.com/googleapis/google-cloud-node-core/blob/main/packages/google-auth-library-nodejs/src/auth/computeclient.ts)
• Go's idtoken package hardcodes it as well:(https://github.com/googleapis/google-api-go-client/blob/main/idtoken/compute.go), while the newer cloud.google.com/go/auth exposes it as an opt-in ComputeTokenFormat option with standard as the default:(https://github.com/googleapis/google-cloud-go/blob/main/auth/credentials/idtoken/compute.go)
• Java has opt-in IdTokenProvider.Option.FORMAT_FULL (and LICENSES_TRUE): (https://github.com/googleapis/google-cloud-java/blob/main/google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/ComputeEngineCredentials.java)
• C# has opt-in OidcTokenFormat (Full / FullWithLicences):(https://github.com/googleapis/google-api-dotnet-client/blob/main/Src/Support/Google.Apis.Auth/OAuth2/ComputeCredential.cs)

So among Python, Node, Go, Java, and C#, PHP is currently the only one without a way to get the full-format token — and the opt-in shape in this PR is the same design Java, C#, and the new Go library settled on, which I'd agree beats Python/Node hardcoding it.

The use case is the one from #526: service-to-service calls on Cloud Run, where the receiving service verifies the incoming ID token and authorizes on the calling service account's email claim, which the standard format omits. We're not reading it back through getLastReceivedToken — the middleware attaches it to the outgoing request as usual; the format only changes what the receiver sees after verifying the JWT.

The handler workaround does work, but one subtle issue pushed me toward a first-class option: getCacheKey() is the token URI, so with the constructor arg a full-format credential naturally gets its own cache key, while with the rewriting handler the format never makes it into the key — a standard-format and a full-format credential for the same audience would collide in a shared FetchAuthTokenCache pool. It also couples user code to the /identity path, which feels like an implementation detail of this class.

Happy to also add the licenses flag for parity with Java/C#/Go, or adjust the parameter shape to whatever fits this library's conventions best.