Feat/add AgentCore Policy integration with user identity propagation

CHANGELOG.md

@@ -7,10 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- User identity propagation from frontend JWT through M2M tokens to Cedar policy evaluation at AgentCore Gateway
+- Cedar Policy Engine and Cedar Policy lifecycle management via Custom Resource Lambda (`infra-cdk/lambdas/cedar-policy/`)
+- Cognito V3 Pre-Token Generation Lambda for injecting custom claims into M2M tokens (`infra-cdk/lambdas/pretoken-v3/`)
+- Cedar policy file with custom claim-based access control — two versions for allow/deny testing (`gateway/policies/policy.cedar`)
+- Cognito ESSENTIALS tier for V3 Pre-Token Lambda trigger support
+- Direct Cognito `/oauth2/token` call with `aws_client_metadata` for user identity propagation (Approach 1) across all 6 agent patterns
+- Alternative `@requires_access_token` decorator approach (Approach 2) documented and commented out in each pattern's `tools/gateway.py`
+- Identity propagation and Cedar policy documentation (`docs/IDENTITY_POLICY.md`)
+- Cedar policy syntax, capabilities, and reference documentation (`docs/CEDAR_POLICY_GUIDE.md`)
+- Identity provider swap and Gateway interceptors guide (`docs/REPLACING_COGNITO.md`)
+
 ### Changed
 
+- Updated all 6 agent patterns to pass `user_id` to Gateway client for identity-aware M2M tokens
+- Updated NAT Gateway documentation in `docs/DEPLOYMENT.md` for VPC mode with identity propagation
+- Updated root `README.md` architecture flow and project structure
 - Updated architecture diagram with latest logos (`docs/architecture-diagram/FAST-architecture-20260403.png`)
 
+### Fixed
+
+- ZIP packager: permissive pattern directory reader with recursive subdirectory support
+- ZIP packager: added `patterns/utils/` to deployment package
+- ZIP packager: renamed repo-root `tools/` to `agentcore_tools/` to avoid conflict with pattern's `tools/` directory
+- ZIP packager: dynamic entry point detection instead of hardcoded `basic_agent.py`
+- Cognito domain creation ordering to resolve "Internal error from downstream service" with newer CDK versions
+- `langgraph>=1.1.5` version bump to fix `ServerInfo` import error
+- `copilotkit>=0.1.84` version bump to fix compatibility with newer langgraph
+- Added placeholder graph in `ActorAwareLangGraphAgent.__init__` for newer copilotkit validation
+
 ## [0.4.1] - 2026-03-25
 
 ### Added

README.md

@@ -55,7 +55,7 @@ What comes next? That's up to you, the developer. With your requirements in mind
 The out-of-the-box architecture is shown above. The diagram illustrates the authentication flows across the stack:
 1. User login to the frontend (Cognito User Pool — Authorization Code grant): The user authenticates with Cognito via the web application hosted on AWS Amplify. Cognito issues a JWT access token for the session.
 2. Frontend to AgentCore Runtime (Cognito User Pool JWT validation): The frontend passes the user's JWT in the Authorization header. The Runtime validates the token against the Cognito User Pool.
-3. AgentCore Runtime to AgentCore Gateway (OAuth2 Client Credentials / M2M): The Runtime authenticates as a service using the OAuth2 Client Credentials grant — independent of the user's identity. AgentCore Identity manages token retrieval via the Token Vault.
+3. AgentCore Runtime to AgentCore Gateway (OAuth2 Client Credentials / M2M): The Runtime authenticates using the OAuth2 Client Credentials grant with user identity propagated into the M2M token via the Cognito V3 Pre-Token Lambda. The Gateway evaluates Cedar policies against the user's claims to enforce fine-grained access control.
 4. Frontend to API Gateway (Cognito User Pool JWT validation): API requests are authenticated using a Cognito User Pools Authorizer with the same user JWT from Flow 1.
 
 ### Tech Stack
@@ -100,7 +100,9 @@ fullstack-agentcore-solution-template/
 │   │   └── fast-main-stack.ts
 │   ├── bin/                # CDK app entry point
 │   ├── lambdas/            # Lambda function code
+│   │   ├── cedar-policy/    # Cedar Policy Engine lifecycle
 │   │   ├── oauth2-provider/ # OAuth2 Credential Provider lifecycle
+│   │   ├── pretoken-v3/     # Cognito V3 Pre-Token Generation Lambda
 │   │   ├── feedback/       # Feedback API handler
 │   │   └── zip-packager/   # Runtime ZIP packager
 │   └── config.yaml         # Deployment configuration
@@ -130,6 +132,8 @@ fullstack-agentcore-solution-template/
 │   └── code_interpreter/   # AgentCore Code Interpreter integration
 │       └── code_interpreter_tools.py # Core implementation
 ├── gateway/                # Gateway utilities and tools
+│   ├── policies/           # Cedar policy definitions
+│   │   └── policy.cedar    # Department-based access control policy
 │   └── tools/              # Gateway tool implementations
 │       └── sample_tool/    # Example Gateway tool
 ├── scripts/                # Deployment and utility scripts
@@ -151,6 +155,9 @@ fullstack-agentcore-solution-template/
 │   ├── AGENT_CONFIGURATION.md # Agent setup guide
 │   ├── MEMORY_INTEGRATION.md # Memory integration guide
 │   ├── GATEWAY.md          # Gateway integration guide
+│   ├── IDENTITY_POLICY.md  # Identity propagation & Cedar policy guide
+│   ├── CEDAR_POLICY_GUIDE.md # Cedar policy syntax, capabilities & reference
+│   ├── REPLACING_COGNITO.md # Identity provider swap & Gateway interceptors guide
 │   ├── RUNTIME_GATEWAY_AUTH.md # M2M authentication workflow
 │   ├── STREAMING.md        # Streaming implementation guide
 │   ├── TOOL_AC_CODE_INTERPRETER.md # Code Interpreter guide

docs/AGENT_CONFIGURATION.md

@@ -76,8 +76,8 @@ bedrock_model = ChatBedrock(
 **Gateway Integration** (`patterns/langgraph-single-agent/langgraph_agent.py`):
 
 ```python
-# Create MCP client for Gateway
-mcp_client = await create_gateway_mcp_client(access_token)
+# Create MCP client for Gateway with user identity propagation
+mcp_client = await create_gateway_mcp_client(user_id)
 
 # Load tools from Gateway
 tools = await mcp_client.get_tools()
@@ -158,7 +158,7 @@ EXPOSE 8080
 CMD ["python", "your_agent.py"]
 ```
 
-**For ZIP deployment**: No Dockerfile is needed. The ZIP packager automatically bundles your `patterns/<pattern>/` directory along with `gateway/` and `tools/` directories, plus dependencies from `requirements.txt`.
+**For ZIP deployment**: No Dockerfile is needed. The ZIP packager automatically bundles your `patterns/<pattern>/` directory along with `patterns/utils/`, `gateway/`, and `tools/` directories, plus dependencies from `requirements.txt`.
 
 ### Step 4: Update CDK Configuration