fix(schema): relax request header allowlist to accept documented header patterns

[aidandaly24]

Summary

Relaxes the request header allowlist validation to accept the broader set of HTTP header names described in the AgentCore Runtime header allowlist documentation.

Previously only Authorization or X-Amzn-Bedrock-AgentCore-Runtime-Custom-* were accepted. Now any valid HTTP header name is accepted provided it:

• Contains only alphanumeric characters, hyphens, and underscores
• Does NOT start with x-amz- (reserved for SigV4)
• Does NOT start with x-amzn- (reserved) unless it is X-Amzn-Bedrock-AgentCore-Runtime-Custom-*

Examples now accepted: X-Api-Key, X-Custom-Signature, Authorization, X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId

The service itself enforces the broader restricted-header list (e.g. Cookie, Host, Content-Length); the CLI/CDK only validate the structural rules so users get fast feedback for the common reserved-prefix cases.

Changes

• src/schema/schemas/agent-env.ts — Updated RequestHeaderAllowlistSchema to use superRefine with per-branch error messages. Exports checkAllowlistHeader() and HEADER_NAME_PATTERN for shared use.
• src/cli/commands/shared/header-utils.ts — Updated normalizeHeaderName to pass through X-* prefixed headers unchanged. Bare suffixes still auto-prefix for backward compatibility. validateHeaderAllowlist delegates to the schema-exported checkAllowlistHeader(). Added case-insensitive deduplication in parseAndNormalizeHeaders.
• src/cli/commands/shared/__tests__/header-utils.test.ts — Tests for X-Api-Key/X-Custom-Signature pass-through, restricted prefix rejection (x-amz-*, x-amzn-trace-id), case-insensitive dedup, underscore support, prefix canonicalization with suffix preservation.
• src/cli/primitives/AgentPrimitive.tsx, src/cli/tui/screens/agent/AddAgentScreen.tsx, src/cli/tui/screens/generate/GenerateWizardUI.tsx — Updated CLI flag help text and TUI hints to clarify X-prefixed pass-through and Custom- auto-prefix behavior.

Scope

This PR delivers the CLI-side validation portion only. The @aws/agentcore-cdk pin in src/assets/cdk/package.json is intentionally not bumped here — bumping to a published version that still ships the old strict schema would only move the failure to deploy time. End-to-end deploy support is gated on:

1. Companion PR aws/agentcore-l3-cdk-constructs#218 merging (mirror schema fix)
2. A new @aws/agentcore-cdk alpha being published with that fix
3. A follow-up PR bumping the pin in src/assets/cdk/package.json to that version

Issue #1151 should remain open until step 3 lands.

Related Issue

Refs #1151 (CLI-side validation only; full end-to-end fix gated on CDK pin bump per scope above)

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Testing

• npm run test:unit — header-utils tests: 44/44 pass; full suite: 3778/0 pass
• npx tsc --noEmit — typecheck passes
• npm run lint — no warnings

Test coverage added for:

• normalizeHeaderName passes through X-Api-Key, X-Custom-Signature, X-Request-Id unchanged
• normalizeHeaderName canonicalizes Runtime-Custom- prefix casing while preserving suffix as-typed
• Bare suffixes (no X- prefix) still auto-prefix with Runtime-Custom- for backward compatibility
• validateHeaderAllowlist rejects x-amz-* with "reserved for AWS request signing" error
• validateHeaderAllowlist rejects x-amzn-trace-id (and other non-Runtime-Custom x-amzn-*)
• Case-insensitive deduplication for X-prefixed headers (X-Api-Key, x-api-key → one entry)
• Headers with underscores accepted (e.g. X-My_Custom_Header)

Checklist

• I have read the CONTRIBUTING document
• I have added necessary tests that prove my fix is effective
• I have updated the documentation accordingly
• My changes generate no new warnings
• Dependent CDK change merged and published — gated on companion PR aws/agentcore-l3-cdk-constructs#218; pin bump tracked as a follow-up PR

---

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

[agentcore-cli-automation]

Thanks for pushing this forward. I think the fix is on the right track but is under-relaxing the validation relative to what the linked AWS documentation now describes. See the inline comment on agent-env.ts for details — I think that needs to be resolved before merging. The other note is a question/clarification rather than a blocker.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.36%	9115 / 21020
🔵	Statements	42.63%	9678 / 22699
🔵	Functions	40.19%	1578 / 3926
🔵	Branches	40.16%	5893 / 14672

Generated in workflow #2892 for commit 0855c6c by the Vitest Coverage Report Action

[agentcore-cli-automation]

Thanks for iterating on the earlier feedback — the broadened RFC 7230 regex in the schema now matches the AWS docs (e.g. X-Api-Key, X-Custom-Signature), and the pass-through branch in normalizeHeaderName cleanly avoids silently rewriting non-AgentCore X-* headers. The test additions are on point.

Two issues worth addressing before this merges — details in the inline comments. Neither is a logic bug in this repo, but together they would leave users with a confusing end-to-end experience.

[agentcore-cli-automation]

Thanks for the follow-ups — the schema broadening, the updated help text, and the normalizeHeaderName pass-through for X-Api-Key / X-Custom-Signature all look good and correctly address the earlier review feedback.

Two blocking issues before this can merge:

1. The pinned @aws/agentcore-cdk version does not exist on npm. src/assets/cdk/package.json pins ^0.1.0-alpha.29, but the latest published version is 0.1.0-alpha.28 and 0.1.0-alpha.29 returns version not found from the registry. Inspecting the published 0.1.0-alpha.28 tarball confirms it still carries the old strict predicate (val === 'Authorization' || val.startsWith(HEADER_ALLOWLIST_PREFIX)). I also don't see the mirror change in the agentcore-l3-cdk-constructs repo's main branch (still at alpha.22 with the old schema). As shipped, this PR would make every agentcore create scaffold fail at npm install. See the inline comment on src/assets/cdk/package.json.

2. The format CI check is failing on src/schema/schemas/agent-env.ts. Needs npm run format + a commit. See the inline comment.

Everything else (the schema/normalizer logic, the new tests, the updated help strings in the CLI flag and both TUI screens) looks reasonable to me.

[agentcore-cli-automation]

Thanks for the quick turnaround on the pin — that unblocks agentcore create. Two blocking issues still remain, both flagged inline:

1. format CI is still failing, just on different files now. The edits to the two TUI help strings in AddAgentScreen.tsx and GenerateWizardUI.tsx broke Prettier formatting (per the CI log on the latest commit). Needs another npm run format + commit.

2. The end-to-end gap is still open. Pinning back to ^0.1.0-alpha.28 restores npm install, but the published 0.1.0-alpha.28 tarball still ships the old strict predicate (val === 'Authorization' || val.startsWith(HEADER_ALLOWLIST_PREFIX)) — I verified this by pulling the tarball from the registry. The agentcore-l3-cdk-constructs repo's main is also still on alpha.22 with the old schema, and no mirror PR appears to have landed. So as shipped, the CLI now tells users X-Api-Key / X-Custom-Signature / X-Amzn-Bedrock-AgentCore-Runtime-User-* are valid (help text + Zod schema + normalizeHeaderName pass-through), but the CDK synth step in agentcore deploy will still reject them with the old error message. That's the exact failure mode my previous review flagged — the pin was "fixed" by reverting rather than by bumping, which only trades one broken state for another.

The cleanest path is still: land + publish the mirror change in agentcore-l3-cdk-constructs first, then bump this pin to whatever alpha version ends up carrying it, then merge this PR. See the inline comment on src/assets/cdk/package.json for the specific options.

Everything else in the PR (schema, normalizer, tests, help-text copy) looks good — the logic side of the fix is in the right place.

[agentcore-cli-automation]

Reviewed the PR in its current state (commit 76b44cc). The scope narrowing to "CLI-only half-fix" (Option 3) and the corresponding PR-description / issue-#1151 bookkeeping all look good, the schema relaxation matches the AWS docs, and the prior reviewer concerns (stale help strings, pin bumped to a non-existent version, HEADER_ALLOWLIST_PATTERN re-export) have been addressed.

Found one new blocker that hasn't been raised yet: the snapshot for src/assets/cdk/package.json wasn't regenerated after bumping the @aws/agentcore-cdk pin, so assets.snapshot.test.ts is currently failing in CI (unit-test (20.x, 1/3)). See the inline comment on src/assets/cdk/package.json.

Note: the format CI failure on this run is caused only by .github/harness/prompts/review.md, which is untouched by this PR and is a pre-existing issue on main — not a blocker for this PR.

[agentcore-cli-automation]

Reviewed the current state of the PR (head c8abffa). The scope narrowing to "CLI-only half-fix" is well-documented in the PR description, the schema relaxation matches the linked AWS docs, the normalizeHeaderName pass-through branch correctly avoids silently rewriting X-Api-Key / X-Custom-Signature, and all previously-raised blockers (help-text staleness, nonexistent CDK pin, format failures, snapshot drift) have been addressed. All CI checks are passing on the latest commit.

One soft concern worth thinking about before merge — see the inline comment on AddAgentScreen.tsx. It's specifically a consequence of the Option-3 scope and is borderline between "acceptable trade-off the PR already documents" and "worth holding until the constructs mirror publishes", so I'll leave the call to you.

[aidandaly24]

Closing: fresh run with CI fix improvements

[github-actions]

Package Tarball

aws-agentcore-0.13.1.tgz

How to install

npm install https://github.com/aws/agentcore-cli/releases/download/pr-1163-tarball/aws-agentcore-0.13.1.tgz

[agentcore-cli-automation]

Reviewed the PR in its current state (head c8abffa). All the serious issues I would have flagged — schema under-relaxation relative to the AWS docs, stale help/hint copy, the nonexistent ^0.1.0-alpha.29 pin, format CI failures, the assets.snapshot.test.ts drift after the pin bump, the bare-prefix validation tightening, and the end-to-end deploy-flow gap caused by the unpublished CDK mirror change — have already been raised in the existing review thread and either fixed or explicitly accepted as the documented trade-off of the Option 3 (CLI-only half-fix) scope.

No new blockers from my pass:

• Schema change correctly mirrors the linked AWS docs (RFC 7230 token characters) and the comment block accurately describes why only syntactic validation is done client-side.
• normalizeHeaderName's ordering is correct — the Custom- prefix check runs before the broad AgentCore- prefix check, so X-Amzn-Bedrock-AgentCore-Runtime-Custom-Foo keeps its canonical Custom- casing rather than being truncated back to the broad prefix. The X- pass-through branch correctly avoids silently rewriting X-Api-Key / X-Custom-Signature.
• Test additions cover the three new behaviors (non-Custom AgentCore headers preserved, case canonicalization on the broad prefix, arbitrary X-* pass-through) and don't introduce any mocking — they exercise the real functions directly.
• No telemetry instrumentation is warranted here; this is a pure validation relaxation on an existing code path, not a new user-facing feature.

The one live trade-off (help text + schema advertise X-Api-Key et al. as valid, but agentcore deploy → CDK synth will still reject them until @aws/agentcore-cdk publishes the mirror change and the pin is bumped in a follow-up) is explicitly called out in both the PR description and the prior reviewer's soft-concern comment, and issue #1151 is being kept open to track the end-to-end fix. That's a reasonable way to land the CLI-side half.

LGTM.

[tejaskash]

Thanks for the cleanup — the broader allowlist matches the documented service behavior and the new tests exercise the happy paths. Two cross-cutting concerns that I'd like resolved before merge, plus a few smaller line-level notes.

1. PR description does not match the code. The description claims a reserved-prefix rejection layer (isValidAllowlistHeader, x-amz-* and non-Custom x-amzn-* rejected with "reserved for AWS request signing" errors), corresponding rejection tests, and a case-insensitive dedup added to parseAndNormalizeHeaders "per AWS docs." None of that is in the diff: there is no helper, no reserved-prefix rejection, no rejection tests for x-amz-* / x-amzn-trace-id, and parseAndNormalizeHeaders is unchanged. Please either rewrite the description to reflect what the PR actually does, or add the missing logic and tests.

2. CDK pin bump is included despite the description saying it is deferred. The description says "a follow-up commit will bump the pin in src/assets/cdk/package.json," but the diff bumps @aws/agentcore-cdk from ^0.1.0-alpha.19 to ^0.1.0-alpha.28 — a 9-version jump. Please confirm alpha.28 actually contains the matching schema relaxation (companion CDK PR aws/agentcore-l3-cdk-constructs#218) and that no other changes between alpha.19..alpha.28 affect users of the vended CDK app (construct API shifts, prop renames, etc.). Also worth noting the assets snapshot was the only test that needed updating, which is suspicious for a 9-version jump.

Line-level notes inline.

[aidandaly24]

Summary for reviewers

This PR was rewritten in commit 0855c6c6 (force-pushed to fix/1151-d9c3118f). All earlier review comments from agentcore-cli-automation (2026-05-07) were against the original agent-authored code, which has been replaced. Status of each blocker raised:

Original bot finding	Status on 0855c6c6
Over-relaxed regex (X-Amzn-Bedrock-AgentCore-* only)	Fixed — pattern now [A-Za-z0-9\-_]+ per AWS docs, with x-amz-* and x-amzn-* (except Runtime-Custom-*) explicitly blocked
HEADER_ALLOWLIST_BROAD_PREFIX invented (no such concept in docs)	Removed
normalizeHeaderName silently rewrote X-Api-Key	Fixed — X--prefixed names pass through unchanged
agentcore-l3-cdk-constructs mirror not landed	aws/agentcore-l3-cdk-constructs#218 open with matching schema fix
CDK pin bumped to non-existent / old-schema version	Pin reverted to ^0.1.0-alpha.19; bump deferred to follow-up after #218 publishes
Snapshot test failing due to pin bump	Pin not bumped, snapshot file removed from PR
format CI failing on TSX files	Resolved (re-run pending on latest commit)
TUI help advertising X-Api-Key while deploy can't accept it	Help text updated; scope clarified in PR description that deploy support gates on follow-up pin bump
Stale flag-help/TUI strings	Updated in 0855c6c6 to match new behavior

Replies on the more recent (tejaskash) review have been re-posted with verification commands; my earlier replies were against a phantom branch and did not actually point at the live PR head — apologies for the noise.