Agent: replace existing auth headers during auto-auth re-authentication

[debben]

Description

This PR fixes a Vault Agent auto-auth bug where auth headers could accumulate on the shared API client across re-authentication cycles.

When an auth method returned headers (for example, Kerberos Authorization), re-authentication reused the same client and appended header values each cycle. Over time, requests could include duplicate/stale header values, causing authentication failures.

This change makes header handling explicit and safe:

• Added a new API client method to set a single header key/value using replacement semantics.
• Updated auto-auth header application to:
  • replace existing values when the header key is already present
  • add values only when the key is not present
• Added/updated tests to cover:
  • single-header replacement behavior on the API client
  • regression coverage ensuring headers do not duplicate across re-authentication

Issue reference:

• Fixes Vault Agent auto-auth re-authentication appends headers instead of replacing existing header keys #32022

Testing

• Ran targeted API client test for single-header replacement behavior.
• Ran targeted auth regression test:
  • TestAuthHandler_HeaderNotDuplicatedOnReauth
• Ran vault agent built from this branch against a local vault server instance per the testing instructions in Vault Agent auto-auth re-authentication appends headers instead of replacing existing header keys #32022 and verified this resolved subsequent re-authentication attempts failing from KRB_AP_ERR_SKEW

Risk / Impact

• Scope is limited to header mutation behavior in client/auth flows.
• No intended behavior change for unrelated auth flows.
• Low risk; covered by focused unit/regression tests.

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.
• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've documented the impact of any changes to security controls.

Security controls impact:

• No new access control mechanism was introduced.
• No logging pipeline changes were introduced.
• Change is limited to request header replacement semantics to prevent stale/duplicate auth header reuse.

[vercel]

Deployment failed with the following error:

The `vercel.json` schema validation failed with the following message: should NOT have additional property `public`

Learn More: https://vercel.com/docs/concepts/projects/project-configuration

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vault-ui	Error		Jul 1, 2026 5:42pm

[hashicorp-cla-app]

Thank you for your submission! We require that all contributors sign our Contributor License Agreement ("CLA") before we can accept the contribution. Read and sign the agreement

Learn more about why HashiCorp requires a CLA and what the CLA includes

_{Have you signed the CLA already but the status is still pending? Recheck it.}