feat(a2a): Add API key authentication provider

[adamfweidman]

Summary

Adds ApiKeyAuthProvider for authenticating with remote A2A agents using API keys. Keys are sent as HTTP headers with support for dynamic credential resolution via environment variables ($ENV_VAR) and shell commands (!command).

Details

• ApiKeyAuthProvider sends API key as a configurable header (default: X-API-Key)
• Re-resolves !command-based keys on 401/403 with retry limit; skips retry for literal/env-var keys since resending identical headers is pointless
• Wires up apiKey case in A2AAuthProviderFactory
• Simplifies ApiKeyAuthConfig to header-only (query/cookie not yet supported)
• Changes BaseA2AAuthProvider retry fields to protected so subclasses can implement custom retry logic
• Adds .min(1) validation on HTTP auth string fields in Zod schema

Related Issues

Related to #17597

How to Validate

npm run test

Pre-Merge Checklist

• Added/updated tests (if needed)
• Validated on required platforms/methods:
  • MacOS
    • npm run

[gemini-cli]

Hi @adamfweidman, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[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 A2A agents by introducing a dedicated API key authentication provider. It allows for flexible API key management, including dynamic resolution from environment variables or shell commands, and incorporates intelligent retry mechanisms for command-based keys. The changes also refine authentication configuration schemas, improving validation and clarity for developers.

Highlights

• New API Key Authentication Provider: Introduced ApiKeyAuthProvider to enable authentication with remote A2A agents using API keys, supporting dynamic credential resolution via environment variables ($ENV_VAR) and shell commands (!command).
• Dynamic Key Resolution and Retry Logic: Implemented logic to re-resolve !command-based API keys on 401/403 HTTP responses with a retry limit, while skipping retries for literal or environment variable keys as they would not change.
• Simplified API Key Configuration: Streamlined ApiKeyAuthConfig to exclusively support API keys sent as HTTP headers, removing in and location properties for query/cookie support which are not yet implemented.
• Enhanced Authentication Schema Validation: Updated Zod schemas for HTTP authentication to include .min(1) validation for token, username, and password fields, and refined basic authentication error messages for clarity.
• Provider Factory Integration: Integrated the new ApiKeyAuthProvider into the A2AAuthProviderFactory, allowing it to be created based on the apiKey configuration type.

Changelog

• packages/core/src/agents/agentLoader.test.ts
  • Removed in: header property from API key configuration examples in tests.
  • Updated the expected error message for basic authentication failures to be more specific.
• packages/core/src/agents/agentLoader.ts
  • Removed the in property from FrontmatterAuthConfig related to API keys.
  • Removed the in property from apiKeyAuthSchema in the Zod validation schema.
  • Updated httpAuthSchema to add .min(1) validation for token, username, and password fields.
  • Refined the superRefine logic for basic authentication to provide distinct error messages for missing username and password.
  • Removed the location property when converting frontmatter API key configuration to the internal config.
• packages/core/src/agents/auth-provider/api-key-provider.test.ts
  • Added a new test file for ApiKeyAuthProvider covering initialization, header generation, and retry logic for various key types.
• packages/core/src/agents/auth-provider/api-key-provider.ts
  • Added a new class ApiKeyAuthProvider to handle API key authentication, supporting literal, environment variable, and command-based key resolution.
  • Implemented initialize() to resolve the API key and headers() to return the appropriate HTTP headers.
  • Included shouldRetryWithHeaders() logic to re-resolve command-based keys on 401/403 errors up to a maximum retry count.
• packages/core/src/agents/auth-provider/base-provider.ts
  • Changed MAX_AUTH_RETRIES and authRetryCount fields from private to protected to allow subclasses to implement custom retry logic.
• packages/core/src/agents/auth-provider/factory.test.ts
  • Added a new test case to verify that A2AAuthProviderFactory correctly creates and initializes an ApiKeyAuthProvider.
• packages/core/src/agents/auth-provider/factory.ts
  • Imported ApiKeyAuthProvider.
  • Added a case 'apiKey' to the A2AAuthProviderFactory.create method to instantiate and initialize the new ApiKeyAuthProvider.
• packages/core/src/agents/auth-provider/types.ts
  • Removed the location property from ApiKeyAuthConfig, simplifying it to header-only support.
  • Updated JSDoc for ApiKeyAuthConfig to reflect header-only support and default header name.

Activity

• The pull request author, adamfweidman, created this pull request to introduce API key authentication.
• The author provided a detailed summary and specific implementation details in the pull request description.
• The author included validation steps and a pre-merge checklist, indicating thorough preparation.

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: +121 B (0%)

Total Size: 24.5 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	24.5 MB	+121 B (0%)
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces the ApiKeyAuthProvider for A2A agents, enabling authentication via API keys in HTTP headers and supporting dynamic key resolution from environment variables and shell commands. However, a critical command injection vulnerability exists due to the allowance of API keys to be resolved from shell commands within ApiKeyAuthProvider, specifically in the initialize and shouldRetryWithHeaders methods. This poses a significant Remote Code Execution (RCE) risk. It is strongly recommended to disable this feature entirely. On a positive note, the PR also improves validation in agentLoader.ts and includes comprehensive unit tests.

[sehoon38]

.

[sehoon38]

LGTM