feat(a2a): add value-resolver for auth credential resolution

[adamfweidman]

Summary

This PR adds a value-resolver for authentication credentials in remote agents, allowing secrets to be resolved from environment variables or shell commands.

Details

• Implemented resolveAuthValue to support $ENV_VAR and !command syntax.
• Added maskSensitiveValue for secure logging of credentials.
• Updated AgentLoader to parse auth configuration from agent markdown frontmatter.
• Added comprehensive unit tests for value resolution and agent parsing.

Related Issues

Fixes #18637

How to Validate

Run unit tests for the core package:

npm run test -w @google/gemini-cli-core -- src/agents/auth-provider/value-resolver.test.ts src/agents/agentLoader.test.ts

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run

[gemini-code-assist]

Summary of Changes

Hello @adamfweidman, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the authentication capabilities for remote agents by introducing a flexible mechanism to resolve credentials from external sources like environment variables or shell commands. It integrates this new resolution logic into the agent loading process, allowing remote agents to define their authentication requirements directly within their markdown frontmatter. This change improves security by enabling dynamic credential management and secure logging, while also providing comprehensive validation for auth configurations.

Highlights

• Auth Credential Resolution: Introduced a new value-resolver module that enables authentication credentials to be dynamically resolved from environment variables (e.g., $MY_API_KEY) or by executing shell commands (e.g., !get-secret-command). This provides a flexible and secure way to manage sensitive information.
• Secure Logging: Added a maskSensitiveValue utility to obscure sensitive credentials in logs, enhancing security by preventing accidental exposure of full secrets.
• Remote Agent Auth Configuration: Updated the AgentLoader to parse authentication configurations directly from remote agent markdown frontmatter. This allows agents to declare their required authentication type (apiKey, HTTP Bearer, HTTP Basic) and associated parameters, including support for the new value resolution syntax.
• Comprehensive Testing: Extensive unit tests have been added for both the value-resolver functionality and the AgentLoader's ability to correctly parse and validate various authentication configurations, ensuring robustness and correctness.

Changelog

• packages/core/src/agents/agentLoader.test.ts
  • Added new test suite for 'remote agent auth configuration'.
  • Included tests for parsing remote agents with apiKey authentication, including key, in, and name fields.
  • Added tests for parsing remote agents with http Bearer authentication, verifying scheme and token.
  • Implemented tests for parsing remote agents with http Basic authentication, checking scheme, username, and password.
  • Added tests to ensure errors are thrown for invalid Bearer auth (missing token), invalid Basic auth (missing username/password), and invalid apiKey auth (missing key).
  • Verified correct conversion of auth configuration from markdown to agent definition, including location mapping for apiKey.
  • Tested parsing of agent_card_requires_auth flag within auth configuration.
• packages/core/src/agents/agentLoader.ts
  • Imported A2AAuthConfig type for authentication configurations.
  • Defined FrontmatterAuthConfig interface to represent authentication configuration in agent frontmatter, supporting apiKey and http types with their respective properties.
  • Added an optional auth property of type FrontmatterAuthConfig to FrontmatterRemoteAgentDefinition.
  • Introduced baseAuthFields for common auth configuration properties like agent_card_requires_auth.
  • Created apiKeyAuthSchema using Zod for validating API key authentication, including key, in, and name.
  • Developed httpAuthSchemaBase using Zod for validating HTTP authentication (Bearer/Basic), including scheme, token, username, and password.
  • Implemented authConfigSchema as a Zod discriminated union of apiKeyAuthSchema and httpAuthSchemaBase, with superRefine for scheme-specific validation (e.g., Bearer requires token, Basic requires username and password).
  • Added an optional auth property to remoteAgentSchema using the new authConfigSchema.
  • Created convertFrontmatterAuthToConfig function to transform FrontmatterAuthConfig into the internal A2AAuthConfig structure, handling type and scheme-specific mappings.
  • Integrated the convertFrontmatterAuthToConfig function into markdownToAgentDefinition to process and convert auth configurations during agent definition parsing.
• packages/core/src/agents/auth-provider/base-provider.ts
  • Added JSDoc comments to BaseA2AAuthProvider and its abstract members (type, headers) for better clarity.
  • Enhanced JSDoc for shouldRetryWithHeaders to explain its purpose, default behavior (401/403 retry), and parameters.
  • Adjusted the shouldRetryWithHeaders logic to reset authRetryCount if the response is not an authentication error.
  • Added JSDoc for the initialize method, clarifying its purpose for async setup in subclasses and providing a no-op default implementation.
• packages/core/src/agents/auth-provider/value-resolver.test.ts
  • Added a new file for testing the value-resolver module.
  • Included tests for resolveAuthValue covering environment variable resolution ($ENV_VAR), including error handling for unset or empty variables.
  • Added tests for resolveAuthValue covering shell command execution (!command), including trimming output, and error handling for empty commands, empty output, and failed commands.
  • Tested resolveAuthValue for literal values, ensuring they are returned as-is.
  • Included tests for resolveAuthValue with escaped literals ($$ and !!) to ensure correct unescaping.
  • Added tests for needsResolution to verify it correctly identifies values requiring resolution (env vars, commands) versus literals.
  • Implemented tests for maskSensitiveValue to check correct masking of long values, and consistent **** output for short or empty values.
• packages/core/src/agents/auth-provider/value-resolver.ts
  • Added a new file implementing the value-resolver module.
  • Implemented resolveAuthValue function to resolve values based on prefixes: $ for environment variables, ! for shell commands, $$ or !! for escaped literals, and plain strings as literals.
  • Included robust error handling within resolveAuthValue for cases like unset environment variables, empty shell commands, commands returning empty output, and command execution failures or timeouts.
  • Implemented needsResolution function to quickly determine if a given string requires resolution (i.e., starts with $ or !).
  • Implemented maskSensitiveValue function to securely mask sensitive strings for logging, showing only the first and last two characters for long strings, and **** for shorter ones.

Activity

• The author has updated relevant documentation and README files, if necessary.
• The author has added or updated tests to cover the new functionality.
• The author has validated the changes on MacOS using npm run.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +2.81 kB (+0.01%)

Total Size: 23.9 MB

Filename	Size	Change
./bundle/gemini.js	23.9 MB	+2.81 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature for resolving authentication credentials from environment variables or shell commands. However, the implementation of arbitrary shell command execution via the ! prefix introduces a high-severity security risk, potentially leading to Remote Code Execution (RCE) if a user is induced to use a malicious agent definition file. It is recommended to disable this feature or implement strict security controls like an allowlist or user confirmation. Additionally, a high-severity suggestion has been made to improve the type safety and robustness of authentication configuration handling in agentLoader.ts to prevent potential runtime errors and enhance maintainability.

[github-actions]

Size Change: +3.41 kB (+0.01%)

Total Size: 23.9 MB

Filename	Size	Change
./bundle/gemini.js	23.9 MB	+3.41 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[galz10]

We should probably update documentation to clearly states that agent files are trusted code and that the !command syntax executes with the user's shell privileges

[adamfweidman]

Because this is just the setup and not actually implemented I was going to wait to add to the docs until the next PR. wdyt