feat: relax requestHeaderAllowlist to broader X-Amzn-Bedrock-AgentCore- namespace (#1151)

[aidandaly24]

Description

Relaxes the runtime requestHeaderAllowlist validation to accept the broader
X-Amzn-Bedrock-AgentCore- namespace, in addition to the existing
Authorization and legacy X-Amzn-Bedrock-AgentCore-Runtime-Custom- prefixed
headers. This brings the CLI in line with the published AWS Bedrock AgentCore
runtime header allowlist:

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-header-allowlist.html

Previously, the schema only accepted exactly Authorization or names starting
with X-Amzn-Bedrock-AgentCore-Runtime-Custom-. Documented runtime headers
such as X-Amzn-Bedrock-AgentCore-Runtime-User-Id and
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id were therefore rejected by the
CLI before deployment, even though the service accepts them.

Changes

Schema (src/schema/schemas/agent-env.ts)

• New exports: HEADER_ALLOWLIST_NAMESPACE_PREFIX ('X-Amzn-Bedrock-AgentCore-'),
  REQUEST_HEADER_ALLOWLIST_PATTERN
  (/^(Authorization|X-Amzn-Bedrock-AgentCore-[A-Za-z0-9-]+)$/i),
  and isAllowedRequestHeader() helper.
• RequestHeaderAllowlistSchema.refine() now uses isAllowedRequestHeader
  with an updated error message that links to the AWS doc.
• Existing HEADER_ALLOWLIST_PREFIX export is preserved (still used for
  auto-prefixing bare names) — no breaking change for consumers.
• Added a "duplicated — keep in sync with agentcore-l3-cdk-constructs" doc
  note above the constants.

Header utilities (src/cli/commands/shared/header-utils.ts)

• Re-exports HEADER_ALLOWLIST_NAMESPACE_PREFIX and isAllowedRequestHeader.
• normalizeHeaderName now recognizes inputs already under the broader
  namespace and canonicalizes their casing without re-wrapping them in the
  Custom- prefix (preventing nonsense names like
  …Runtime-Custom-X-Amzn-Bedrock-AgentCore-Runtime-User-Id). Bare names
  continue to be auto-prefixed with the legacy Custom- prefix for backward
  compatibility.
• validateHeaderAllowlist now runs each parsed header through
  isAllowedRequestHeader and returns a structured error (with doc URL) when
  a name does not match, providing earlier and clearer feedback than relying
  on the Zod refine alone.

Help text

• src/cli/primitives/AgentPrimitive.tsx: updated the
  --request-header-allowlist Commander option description to mention the
  broader namespace and link to the AWS doc.
• src/cli/tui/screens/agent/AddAgentScreen.tsx: updated the dim helper text
  beneath the input field accordingly.

Tests

• src/cli/commands/shared/__tests__/header-utils.test.ts: added cases
  covering normalizeHeaderName for namespace-prefixed inputs (no
  double-prefix; canonical casing) and validateHeaderAllowlist accepting
  the broader namespace.
• src/schema/schemas/__tests__/agent-env.test.ts: new schema-level tests
  for REQUEST_HEADER_ALLOWLIST_PATTERN, isAllowedRequestHeader, and
  RequestHeaderAllowlistSchema (accept/reject cases, max-20 boundary, doc
  URL in error message).

Companion PR

The schema duplicate in aws/agentcore-l3-cdk-constructs has been updated in
lockstep on branch fix/1151-6ed1535c (commit 080c327).

Related Issue

Closes #1151

Documentation PR

N/A — the documented behavior already matches the AWS public docs at
https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-header-allowlist.html;
this PR brings the CLI's runtime validation in line with that doc. The CLI
help text and TUI hints have been updated in this PR.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Targeted test runs (executed locally):

• npx vitest run --project unit src/cli/commands/shared/__tests__/header-utils.test.ts src/schema/schemas/__tests__/agent-env.test.ts
  → 128 / 128 passing across both files.
• npm run typecheck → clean (no errors).
• Pre-commit hooks (prettier, eslint, secretlint) → all green.

CI will exercise the full unit + integ suites on this PR.

Code review

Round 1: 10 findings, all approved.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.21%	9042 / 20923
🔵	Statements	42.49%	9600 / 22593
🔵	Functions	40.04%	1559 / 3893
🔵	Branches	40.01%	5814 / 14529

Generated in workflow #2607 for commit 4b068a0 by the Vitest Coverage Report Action

[agentcore-cli-automation]

Thanks for aligning the allowlist with the published service contract. The schema, normalization, and test coverage all look clean and consistent.

I have one non-code coordination concern worth calling out explicitly before this ships — flagged inline. Otherwise this looks good.

[agentcore-cli-automation]

Release coordination concern (not a code change request, but worth confirming before merge):

This schema is duplicated in agentcore-l3-cdk-constructs, and the generated CDK project consumes the L3 constructs' copy of RequestHeaderAllowlistSchema — not this one — at cdk synth/deploy time. If a CLI release containing this change ships before the companion L3 constructs release (branch fix/1151-6ed1535c) is merged and published to the registry, the flow breaks for users:

1. User runs agentcore create / agentcore add with e.g. X-Amzn-Bedrock-AgentCore-Runtime-User-Id
2. CLI validation passes (new behavior) and writes it into agent-env.yaml
3. CDK synth uses the older L3 constructs schema and rejects it with the old error message

A few ways to de-risk this:

• Confirm the companion L3 PR is merged and a version bump is released before the CLI release that carries this change, and (if applicable) bump the minimum @aws/agentcore-cdk version pinned in the vended CDK project templates / package.json so older constructs can't be resolved.
• Or bundle the updated constructs via the bundled-agentcore-cdk.tgz path (src/cli/templates/CDKRenderer.ts) in the same release.
• Or land + release the L3 constructs change first, then merge this PR.

Could you confirm which path you're taking? Happy to approve once the ordering/versioning is spelled out.

[agentcore-cli-automation]

Minor behavior-change check: the /i flag makes this accept authorization / AUTHORIZATION as well as the canonical Authorization. The previous refine used strict val === 'Authorization', so a YAML containing requestHeaderAllowlist: [authorization] went from rejected → accepted.

This is fine for the CLI entry points that flow through normalizeHeaderName (which canonicalizes casing), but the schema is also applied directly to hand-edited agent-env.yaml values, which aren't renormalized before being passed to the CreateAgentRuntime API. If the service is strict about the canonical Authorization casing in the allowlist array (header names on the wire are case-insensitive, but allowlist entries may not be), users who put lowercase in YAML would get an API-side failure instead of an up-front schema failure.

Could you confirm the service accepts any casing of Authorization in the allowlist? If not, consider dropping the /i or splitting the pattern so Authorization is matched case-sensitively and only the namespace portion is case-insensitive, e.g. /^Authorization$|^X-Amzn-Bedrock-AgentCore-[A-Za-z0-9-]+$/i won't help (/i flag is global) — something like two separate checks or new RegExp without the flag for the first alternative.

[aidandaly24]

Closing: test run from batch agent