fix(auth): align mTLS discovery and enforce fail-fast transport configuration.

[vverman]

This PR resolves two mTLS issues:

(1) it synchronizes the transport and token discovery paths to check for workload certs and library support, preventing mismatched bound tokens, and

(2) it enforces fail-fast error behavior in all transports if mTLS configuration fails, avoiding silent fallback to insecure TLS. These align token and transport states securely.

[gemini-code-assist]

Code Review

This pull request introduces auto-enablement of mTLS when workload certificates are discovered (including at a well-known SPIFFE path) and changes the library's behavior to fail fast with a MutualTLSChannelError instead of silently falling back to standard TLS when mTLS is expected but certificates cannot be loaded. The review feedback suggests several improvements: aligning the environment variable checks in _agent_identity_utils.py to treat any value other than 'true' as disabled, correcting a misleading exception message in sessions.py when a custom request handler is used, and making the SPIFFE certificate path check more robust by using path.isfile and handling potential OSError exceptions.

[vverman]

Summary of Changes

Aligned with PR 17387:

1. State Reset: Reset _is_mtls = False on exceptions in sessions.py, requests.py, and urllib3.py to ensure correct transport state.
2. Custom Transport Fallback: Fallback to standard TLS (no crash) in sessions.py when custom request handler is provided.

New fixes addressing PR 17470 comments:

1. Centralized Env Check: Created _check_use_client_cert_env() helper in _mtls_helper.py and reused it in _agent_identity_utils.py.
2. AIP Env Alignment: Treat any value other than "true" (case-insensitive) as "false" (opt-out) when GOOGLE_API_USE_CLIENT_CERTIFICATE is set.
3. Reverted Fail-Fast: Reverted crashes on missing certificates in all transports, returning to standard TLS fallback. Reverted corresponding docstrings.
4. Warning Logs: Added warning in sessions.py when falling back due to custom transports.
5. Removed SPIFFE Fallback: Removed _WELL_KNOWN_SPIFFE_CERT_PATH logic and tests to fix GKE regression.
6. Cleaned Up Capability Checks: Removed obsolete is_transport_mtls_capable() and associated mock tests.

[nbayati]

Just left a comment on the docstring update, otherwise LGTM!

[parthea]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors mTLS configuration and client certificate checks across multiple transports (aio, requests, urllib3) to respect explicit opt-outs and handle custom transports gracefully by setting _is_mtls to False and logging warnings. It also improves error handling for missing workload certificate paths and introduces corresponding unit tests. The reviewer feedback recommends correcting a docstring mismatch in a new test that incorrectly states an exception is raised, and improving test isolation by clearing all relevant environment variables in the auto-enablement test.