VAULT-43873 return 431 for oversized token headers

[jorge-aquino]

Description

What does this PR do?

Summary

Updates Vault’s token header size validation to return 431 Request Header Fields Too Large instead of 400 Bad Request when authentication token headers exceed the configured size limit.

This applies to oversized X-Vault-Token headers and oversized Authorization: Bearer token values.

Test-first confirmation

I followed the bug test-first workflow for this change. I first ran the focused token-header test with the existing implementation and confirmed it passed with the old 400 Bad Request expectation.

I then changed the focused oversized-token test expectation from http.StatusBadRequest to http.StatusRequestHeaderFieldsTooLarge and reran the test. It failed with expected: 431 and actual: 400, confirming the implementation still returned the old status code before the fix.

Implementation

After confirming the test failed for the expected reason, I updated wrapTokenHeaderSizeHandler in http/util.go so oversized authentication token headers return http.StatusRequestHeaderFieldsTooLarge.

Both oversized token paths were updated:

• X-Vault-Token
• Authorization: Bearer

Test updates

After the implementation change, the focused oversized-token test passed. I then ran the broader token-header test group, which exposed other assertions still expecting 400 for the same oversized token/header validation path.

I updated only the related assertions that exercise oversized token/header validation, including the custom limit case, multiple authorization header case, error response format case, and the API listener enforcement case. The cluster listener skip behavior remains unchanged.

Testing

• go test ./http -run TestTokenHeader_ExceedsDefaultLimit_IsRejected -v
• go test ./http -run TokenHeader -v -count=1
• go test ./http -count=1

All passed.

TODO only if you're a HashiCorp employee

• Backport Labels: If this fix needs to be backported, use the appropriate backport/ label that matches the desired release branch.
  • LTS: If this fixes a critical security vulnerability or severity 1 bug, it will also need to be backported to the current LTS versions of Vault. To ensure this, use all available enterprise labels.
• Jira: If this change has an associated Jira, it's referenced either in the PR description, commit message, or branch name.
• RFC: If this change has an associated RFC, please link it in the description.

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.

Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
vault-ui	Ready	Preview, Comment	Jun 3, 2026 2:10pm

[hashicorp-cla-app]

All committers have signed the CLA.

[jorge-aquino]

Closing this PR because it was opened against the CE repo. l'll reopen the change in vault-enterprise.

[github-actions]

CI Results:
All Go tests succeeded! ✅