@aws/nx-plugin 1.0.0-rc.5 → 1.0.0-rc.51

package/README.md

@@ -137,16 +137,16 @@ pnpm create @aws/nx-workspace my-project
 cd my-project
 
 # Add a tRPC API
-pnpm nx g @aws/nx-plugin:ts#trpc-api
+pnpm nx g @aws/nx-plugin:ts#api --framework=trpc
 
 # Add a Strands AI agent (Python)
 pnpm nx g @aws/nx-plugin:py#agent
 
 # Add a React website
-pnpm nx g @aws/nx-plugin:ts#react-website
+pnpm nx g @aws/nx-plugin:ts#website --framework=react
 
 # Add authentication to your website
-pnpm nx g @aws/nx-plugin:ts#react-website#auth
+pnpm nx g @aws/nx-plugin:ts#website#auth
 
 # Connect your website to your API and agent
 pnpm nx g @aws/nx-plugin:connection
@@ -162,17 +162,17 @@ pnpm nx g @aws/nx-plugin:ts#infra
 | Generator               | Description                                                                                                       |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | `ts#project`            | TypeScript library                                                                                                |
-| `ts#trpc-api`           | tRPC API with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-typescript) |
+| `ts#api`                | TypeScript API (tRPC or Smithy) with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-typescript) |
 | `ts#rdb`                | Relational databases with Aurora RDS                                                                              |
-| `ts#react-website`      | React app (Vite)                                                                                                  |
-| `ts#react-website#auth` | Add Cognito auth to a React website                                                                               |
+| `ts#website`            | React app (Vite)                                                                                                  |
+| `ts#website#auth`       | Add Cognito auth to a website                                                                                     |
 | `ts#infra`              | AWS CDK infrastructure project                                                                                    |
 | `ts#lambda-function`    | TypeScript Lambda with type-safe event sources                                                                    |
 | `ts#mcp-server`         | MCP server (TypeScript)                                                                                           |
 | `ts#agent`              | [Strands Agent](https://strandsagents.com/) (TypeScript)                                                          |
 | `ts#nx-generator`       | Nx generator scaffold                                                                                             |
 | `py#project`            | Python project (uv)                                                                                               |
-| `py#fast-api`           | FastAPI with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-python)      |
+| `py#api`                | Python API (FastAPI) with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-python)      |
 | `py#lambda-function`    | Python Lambda with type-safe event sources                                                                        |
 | `py#mcp-server`         | MCP server (Python)                                                                                               |
 | `py#agent`              | [Strands Agent](https://strandsagents.com/) (Python)                                                              |

package/generators.json

@@ -3,6 +3,33 @@
   "name": "@aws/nx-plugin",
   "version": "0.0.1",
   "generators": {
+    "init": {
+      "factory": "./src/init/generator",
+      "schema": "./src/init/schema.json",
+      "description": "Configure an existing Nx workspace to use the @aws/nx-plugin",
+      "metric": "g66",
+      "guidePages": ["existing-project"]
+    },
+    "agentcore-gateway": {
+      "factory": "./src/agentcore-gateway/generator",
+      "schema": "./src/agentcore-gateway/schema.json",
+      "description": "Generate an AgentCore Gateway project",
+      "metric": "g48"
+    },
+    "agentcore-gateway#mcp-connection": {
+      "factory": "./src/agentcore-gateway/mcp-connection/generator",
+      "schema": "./src/agentcore-gateway/mcp-connection/schema.json",
+      "description": "Connect an AgentCore Gateway to an MCP server",
+      "metric": "g49",
+      "hidden": true
+    },
+    "agentcore-gateway#gateway-connection": {
+      "factory": "./src/agentcore-gateway/gateway-connection/generator",
+      "schema": "./src/agentcore-gateway/gateway-connection/schema.json",
+      "description": "Connect an AgentCore Gateway to another AgentCore Gateway",
+      "metric": "g65",
+      "hidden": true
+    },
     "connection": {
       "factory": "./src/connection/generator",
       "schema": "./src/connection/schema.json",
@@ -23,7 +50,11 @@
         "connection/trpc-rdb",
         "connection/smithy-rdb",
         "connection/ts-mcp-server-rdb",
-        "connection/ts-agent-rdb"
+        "connection/ts-agent-rdb",
+        "connection/ts-agent-gateway",
+        "connection/py-agent-gateway",
+        "connection/agentcore-gateway-mcp",
+        "connection/agentcore-gateway-gateway"
       ]
     },
     "license": {
@@ -180,6 +211,12 @@
       "description": "Generate a TypeScript lambda function",
       "metric": "g21"
     },
+    "ts#dcr-proxy": {
+      "factory": "./src/ts/dcr-proxy/generator",
+      "schema": "./src/ts/dcr-proxy/schema.json",
+      "description": "Generate an OAuth Dynamic Client Registration (DCR) proxy construct for Cognito-authenticated MCP servers",
+      "metric": "g67"
+    },
     "ts#mcp-server": {
       "factory": "./src/ts/mcp-server/generator",
       "schema": "./src/ts/mcp-server/schema.json",
@@ -194,6 +231,13 @@
       "metric": "g17",
       "guidePages": ["nx-generator"]
     },
+    "ts#nx-migration": {
+      "factory": "./src/ts/nx-migration/generator",
+      "schema": "./src/ts/nx-migration/schema.json",
+      "description": "Generator for adding an Nx Migration to an Nx Plugin, applied by nx migrate when users upgrade",
+      "metric": "g68",
+      "guidePages": ["nx-migration"]
+    },
     "ts#nx-plugin": {
       "factory": "./src/ts/nx-plugin/generator",
       "schema": "./src/ts/nx-plugin/schema.json",
@@ -211,7 +255,7 @@
       "factory": "./src/ts/website/app/generator",
       "schema": "./src/ts/website/app/schema.json",
       "description": "Generates a website application",
-      "metric": "g43",
+      "metric": "g60",
       "guidePages": ["website", "react-website"]
     },
     "ts#website#auth": {
@@ -279,6 +323,13 @@
       "metric": "g35",
       "hidden": true
     },
+    "ts#agent#gateway-connection": {
+      "factory": "./src/ts/agent/gateway-connection/generator",
+      "schema": "./src/ts/agent/gateway-connection/schema.json",
+      "description": "Connect a TypeScript Agent to an AgentCore Gateway",
+      "metric": "g50",
+      "hidden": true
+    },
     "py#agent#a2a-connection": {
       "factory": "./src/py/agent/a2a-connection/generator",
       "schema": "./src/py/agent/a2a-connection/schema.json",
@@ -286,10 +337,17 @@
       "metric": "g36",
       "hidden": true
     },
+    "py#agent#gateway-connection": {
+      "factory": "./src/py/agent/gateway-connection/generator",
+      "schema": "./src/py/agent/gateway-connection/schema.json",
+      "description": "Connect a Python Agent to an AgentCore Gateway",
+      "metric": "g51",
+      "hidden": true
+    },
     "ts#sync": {
       "factory": "./src/ts/sync/generator",
       "schema": "./src/ts/sync/schema.json",
-      "description": "TypeScript path alias sync generator",
+      "description": "TypeScript path alias and local workspace dependency sync generator",
       "metric": "g29",
       "hidden": true
     },
@@ -353,28 +411,28 @@
     "ts#dynamodb": {
       "factory": "./src/ts/dynamodb/generator",
       "schema": "./src/ts/dynamodb/schema.json",
-      "description": "Create a DynamoDB project",
-      "metric": "g43"
+      "description": "Create a TypeScript DynamoDB project",
+      "metric": "g61"
     },
     "ts#dynamodb#trpc-connection": {
       "factory": "./src/ts/dynamodb/trpc-connection/generator",
       "schema": "./src/ts/dynamodb/trpc-connection/schema.json",
       "description": "Connect a ts#trpc-api project to a ts#dynamodb project",
-      "metric": "g44",
+      "metric": "g62",
       "hidden": true
     },
     "ts#dynamodb#smithy-connection": {
       "factory": "./src/ts/dynamodb/smithy-connection/generator",
       "schema": "./src/ts/dynamodb/smithy-connection/schema.json",
       "description": "Connect a Smithy backend to a ts#dynamodb project",
-      "metric": "g45",
+      "metric": "g63",
       "hidden": true
     },
     "ts#dynamodb#agent-connection": {
       "factory": "./src/ts/dynamodb/agent-connection/generator",
       "schema": "./src/ts/dynamodb/agent-connection/schema.json",
       "description": "Connect a ts#agent to a ts#dynamodb project",
-      "metric": "g46",
+      "metric": "g64",
       "hidden": true
     },
     "ts#dynamodb#mcp-server-connection": {
@@ -383,6 +441,67 @@
       "description": "Connect a ts#mcp-server to a ts#dynamodb project",
       "metric": "g47",
       "hidden": true
+    },
+    "py#dynamodb": {
+      "factory": "./src/py/dynamodb/generator",
+      "schema": "./src/py/dynamodb/schema.json",
+      "description": "Create a Python DynamoDB project",
+      "metric": "g52"
+    },
+    "py#dynamodb#fast-api-connection": {
+      "factory": "./src/py/dynamodb/fast-api-connection/generator",
+      "schema": "./src/py/dynamodb/fast-api-connection/schema.json",
+      "description": "Connect a py#fast-api project to a py#dynamodb project",
+      "metric": "g53",
+      "hidden": true
+    },
+    "py#dynamodb#agent-connection": {
+      "factory": "./src/py/dynamodb/agent-connection/generator",
+      "schema": "./src/py/dynamodb/agent-connection/schema.json",
+      "description": "Connect a py#agent to a py#dynamodb project",
+      "metric": "g54",
+      "hidden": true
+    },
+    "py#dynamodb#mcp-server-connection": {
+      "factory": "./src/py/dynamodb/mcp-server-connection/generator",
+      "schema": "./src/py/dynamodb/mcp-server-connection/schema.json",
+      "description": "Connect a py#mcp-server to a py#dynamodb project",
+      "metric": "g55",
+      "hidden": true
+    },
+    "py#rdb": {
+      "factory": "./src/py/rdb/generator",
+      "schema": "./src/py/rdb/schema.json",
+      "description": "Create a Python relational database project",
+      "metric": "g56"
+    },
+    "py#rdb#fast-api-connection": {
+      "factory": "./src/py/rdb/fast-api-connection/generator",
+      "schema": "./src/py/rdb/fast-api-connection/schema.json",
+      "description": "Connect a py#fast-api project to a py#rdb project",
+      "metric": "g57",
+      "hidden": true
+    },
+    "py#rdb#agent-connection": {
+      "factory": "./src/py/rdb/agent-connection/generator",
+      "schema": "./src/py/rdb/agent-connection/schema.json",
+      "description": "Connect a py#agent to a py#rdb project",
+      "metric": "g58",
+      "hidden": true
+    },
+    "py#rdb#mcp-server-connection": {
+      "factory": "./src/py/rdb/mcp-server-connection/generator",
+      "schema": "./src/py/rdb/mcp-server-connection/schema.json",
+      "description": "Connect a py#mcp-server to a py#rdb project",
+      "metric": "g59",
+      "hidden": true
+    },
+    "internal#test-matrix": {
+      "factory": "./src/internal/test-matrix/generator",
+      "schema": "./src/internal/test-matrix/schema.json",
+      "description": "Scaffold every generator permutation for end to end tests",
+      "metric": "t1",
+      "hidden": true
     }
   }
 }

package/migrations.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "@aws/nx-plugin",
+  "generators": {
+    "latest-modernize-function-props-cast": {
+      "version": "1.0.0-rc.50",
+      "description": "Replace the legacy angle-bracket FunctionProps type assertion with the modern as syntax in generated API constructs",
+      "implementation": "./src/migrations/latest/modernize-function-props-cast/migration"
+    },
+    "latest-restrict-cors-to-custom-domains": {
+      "version": "1.0.0-rc.50",
+      "description": "Include CloudFront custom domain aliases in restrictCorsTo and UserIdentity callback URLs",
+      "implementation": "./src/migrations/latest/restrict-cors-to-custom-domains/migration"
+    },
+    "latest-terraform-bootstrap-adopt-existing-bucket": {
+      "version": "1.0.0-rc.50",
+      "description": "Adopt an existing Terraform state bucket in the vended bootstrap script when its state object is missing",
+      "implementation": "./src/migrations/latest/terraform-bootstrap-adopt-existing-bucket/migration"
+    }
+  }
+}

package/package.json

@@ -1,48 +1,64 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.51",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",
     "directory": "packages/nx-plugin"
   },
   "private": false,
-  "type": "commonjs",
+  "type": "module",
   "license": "Apache-2.0",
   "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
   "typings": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./sdk/*": {
+      "types": "./src/sdk/*.d.ts",
+      "default": "./src/sdk/*.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "bin": {
-    "aws-nx-mcp": "./bin/aws-nx-mcp.js"
-  },
   "generators": "./generators.json",
   "executors": "./executors.json",
+  "nx-migrations": {
+    "migrations": "./migrations.json"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
   "peerDependencies": {
-    "nx": "22.7.5",
-    "prettier": "3.8.3"
+    "nx": "23.1.0"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "12.1.0",
+    "@astral-sh/ruff-wasm-nodejs": "0.15.22",
+    "@biomejs/js-api": "6.0.0",
+    "@biomejs/wasm-nodejs": "2.5.4",
     "@getgrit/gritql": "0.0.3",
-    "@hey-api/openapi-ts": "0.64.13",
     "@iarna/toml": "2.2.5",
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@nx/devkit": "22.7.5",
-    "@nx/eslint": "22.7.5",
-    "@nx/js": "22.7.5",
-    "@nx/react": "22.7.5",
-    "@nx/vite": "22.7.5",
+    "@nx/devkit": "23.1.0",
+    "@nx/js": "23.1.0",
+    "@nx/react": "23.1.0",
+    "@nx/vite": "23.1.0",
+    "@nxlv/python": "22.2.2",
+    "@phenomnomnominal/tsquery": "6.2.0",
     "@types/estree": "1.0.9",
     "@types/js-yaml": "4.0.9",
     "@types/mdast": "4.0.4",
-    "@nxlv/python": "22.1.4",
-    "@phenomnomnominal/tsquery": "6.2.0",
     "enquirer": "2.4.1",
     "fast-glob": "3.3.3",
-    "jiti": "2.6.1",
-    "js-yaml": "4.2.0",
+    "jiti": "2.7.0",
+    "js-yaml": "4.3.0",
     "license-checker-rseidelsohn": "4.4.2",
     "lodash.camelcase": "4.3.0",
     "lodash.clonedeepwith": "4.5.0",
@@ -58,13 +74,16 @@
     "remark-mdx": "3.1.1",
     "remark-parse": "11.0.0",
     "remark-stringify": "11.0.0",
+    "semver": "7.8.5",
     "spdx-satisfies": "6.0.0",
     "typescript": "6.0.3",
     "unified": "11.0.5",
     "unist-util-visit": "5.1.0",
-    "vite": "8.0.14",
-    "vitest": "4.1.7",
+    "vite": "8.1.5",
+    "vitest": "4.1.10",
     "zod": "4.4.3"
   },
-  "types": "./src/index.d.ts"
+  "devDependencies": {
+    "@types/semver": "7.7.1"
+  }
 }

package/src/agentcore-gateway/attach-upstream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type ProjectConfiguration, type Tree } from '@nx/devkit';
+export interface LocalGatewayUpstream {
+    /**
+     * Gateway target name for the upstream — prefixes its tools as
+     * `<targetName>___<toolName>` both locally and deployed.
+     */
+    targetName: string;
+    /**
+     * Local port the upstream MCP endpoint listens on.
+     */
+    port: number;
+    /**
+     * Project providing the upstream's dev target.
+     */
+    upstreamProjectName: string;
+    /**
+     * Name of the upstream's dev target.
+     */
+    upstreamDevTargetName: string;
+}
+/**
+ * Attach an upstream MCP endpoint (an MCP server or another gateway's local
+ * gateway) to a gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the upstream's dev target, and
+ * registers the upstream in the gateway's local-dev.ts so the local gateway
+ * aggregates its tools.
+ */
+export declare const attachUpstreamToLocalGateway: (tree: Tree, gatewayProject: ProjectConfiguration, gatewayDevTargetName: string, upstream: LocalGatewayUpstream) => Promise<void>;

package/src/agentcore-gateway/attach-upstream.js

@@ -0,0 +1,38 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { joinPathFragments, updateProjectConfiguration } from "@nx/devkit";
+import { applyGritQL } from "../utils/ast.js";
+import { addDependencyToTargetIfNotPresent } from "../utils/nx.js";
+/**
+ * Attach an upstream MCP endpoint (an MCP server or another gateway's local
+ * gateway) to a gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the upstream's dev target, and
+ * registers the upstream in the gateway's local-dev.ts so the local gateway
+ * aggregates its tools.
+ */ export const attachUpstreamToLocalGateway = async (tree, gatewayProject, gatewayDevTargetName, upstream)=>{
+    // 1. Wire dev chain
+    if (gatewayProject.targets?.[gatewayDevTargetName]) {
+        addDependencyToTargetIfNotPresent(gatewayProject, gatewayDevTargetName, {
+            projects: [
+                upstream.upstreamProjectName
+            ],
+            target: upstream.upstreamDevTargetName
+        });
+        updateProjectConfiguration(tree, gatewayProject.name, gatewayProject);
+    }
+    // 2. Register the upstream in the gateway's local local-dev.ts
+    const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');
+    if (tree.exists(serveTsPath)) {
+        const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}/mcp' }`;
+        await applyGritQL(tree, serveTsPath, `or {
+  \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = []\` => \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}]\`,
+  \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [$items]\` => \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}, $items]\` where {
+    $items <: not contains \`'${upstream.targetName}'\`
+  }
+}`);
+    }
+};
+
+//# sourceMappingURL=attach-upstream.js.map

package/src/agentcore-gateway/attach-upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/agentcore-gateway/attach-upstream.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  joinPathFragments,\n  type ProjectConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { applyGritQL } from '../utils/ast';\nimport { addDependencyToTargetIfNotPresent } from '../utils/nx';\n\nexport interface LocalGatewayUpstream {\n  /**\n   * Gateway target name for the upstream — prefixes its tools as\n   * `<targetName>___<toolName>` both locally and deployed.\n   */\n  targetName: string;\n  /**\n   * Local port the upstream MCP endpoint listens on.\n   */\n  port: number;\n  /**\n   * Project providing the upstream's dev target.\n   */\n  upstreamProjectName: string;\n  /**\n   * Name of the upstream's dev target.\n   */\n  upstreamDevTargetName: string;\n}\n\n/**\n * Attach an upstream MCP endpoint (an MCP server or another gateway's local\n * gateway) to a gateway's local gateway.\n *\n * Chains the gateway's dev target onto the upstream's dev target, and\n * registers the upstream in the gateway's local-dev.ts so the local gateway\n * aggregates its tools.\n */\nexport const attachUpstreamToLocalGateway = async (\n  tree: Tree,\n  gatewayProject: ProjectConfiguration,\n  gatewayDevTargetName: string,\n  upstream: LocalGatewayUpstream,\n): Promise<void> => {\n  // 1. Wire dev chain\n  if (gatewayProject.targets?.[gatewayDevTargetName]) {\n    addDependencyToTargetIfNotPresent(gatewayProject, gatewayDevTargetName, {\n      projects: [upstream.upstreamProjectName],\n      target: upstream.upstreamDevTargetName,\n    });\n    updateProjectConfiguration(tree, gatewayProject.name, gatewayProject);\n  }\n\n  // 2. Register the upstream in the gateway's local local-dev.ts\n  const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');\n  if (tree.exists(serveTsPath)) {\n    const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}/mcp' }`;\n    await applyGritQL(\n      tree,\n      serveTsPath,\n      `or {\n  \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = []\\` => \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}]\\`,\n  \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [$items]\\` => \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}, $items]\\` where {\n    $items <: not contains \\`'${upstream.targetName}'\\`\n  }\n}`,\n    );\n  }\n};\n"],"names":["joinPathFragments","updateProjectConfiguration","applyGritQL","addDependencyToTargetIfNotPresent","attachUpstreamToLocalGateway","tree","gatewayProject","gatewayDevTargetName","upstream","targets","projects","upstreamProjectName","target","upstreamDevTargetName","name","serveTsPath","root","exists","entry","targetName","port"],"mappings":"AAAA;;;CAGC,GACD,SACEA,iBAAiB,EAGjBC,0BAA0B,QACrB,aAAa;AACpB,SAASC,WAAW,QAAQ,kBAAe;AAC3C,SAASC,iCAAiC,QAAQ,iBAAc;AAsBhE;;;;;;;CAOC,GACD,OAAO,MAAMC,+BAA+B,OAC1CC,MACAC,gBACAC,sBACAC;IAEA,oBAAoB;IACpB,IAAIF,eAAeG,OAAO,EAAE,CAACF,qBAAqB,EAAE;QAClDJ,kCAAkCG,gBAAgBC,sBAAsB;YACtEG,UAAU;gBAACF,SAASG,mBAAmB;aAAC;YACxCC,QAAQJ,SAASK,qBAAqB;QACxC;QACAZ,2BAA2BI,MAAMC,eAAeQ,IAAI,EAAER;IACxD;IAEA,+DAA+D;IAC/D,MAAMS,cAAcf,kBAAkBM,eAAeU,IAAI,EAAE;IAC3D,IAAIX,KAAKY,MAAM,CAACF,cAAc;QAC5B,MAAMG,QAAQ,CAAC,SAAS,EAAEV,SAASW,UAAU,CAAC,0BAA0B,EAAEX,SAASY,IAAI,CAAC,OAAO,CAAC;QAChG,MAAMlB,YACJG,MACAU,aACA,CAAC;mHAC4G,EAAEG,MAAM;yHACF,EAAEA,MAAM;8BACnG,EAAEV,SAASW,UAAU,CAAC;;CAEnD,CAAC;IAEA;AACF,EAAE"}

package/src/agentcore-gateway/files/cedar/policies/README.md

@@ -0,0 +1,61 @@
+# Cedar policies for <%= nameClassName %>
+
+Every `.cedar` file in this directory is deployed as a separate `Policy`
+resource attached to this gateway's `PolicyEngine`. The engine runs in
+`ENFORCE` mode, so policies are evaluated and decisions are enforced at
+runtime.
+
+## Default policy
+
+<%_ if (auth === 'cognito') { _%>
+`permit-all.cedar` permits any Cognito-authenticated caller
+(`principal is AgentCore::OAuthUser`). The gateway's JWT authorizer already
+validates the token's user pool and client before policies are evaluated, so
+any principal that reaches the engine is an authenticated OAuth user. Tighten
+this by matching JWT claims (e.g. `principal.scope`) — see the
+[AgentCore common policy patterns](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-common-patterns.html).
+<%_ } else { _%>
+`permit-all.cedar` permits any IAM caller from the deploying AWS account.
+It is scoped to your account because AgentCore's policy validator rejects
+truly unrestricted permits (`permit (principal, action, resource)`) as
+"Overly Permissive".
+<%_ } _%>
+
+**If you delete this file without adding replacement `permit` policies, the
+gateway will deny every request** — Cedar uses a default-deny evaluation
+model, so every request requires at least one matching `permit` to be
+allowed.
+
+## Template variables
+
+Policies are [EJS](https://ejs.co/) templates rendered at synth/plan time
+with the following variables in scope:
+
+- `<%%= gatewayArn %>` — this gateway's ARN
+- `<%%= accountId %>` — the AWS account this gateway is deployed into
+
+Add your own variables (e.g. an agent's role name) where the policies are
+rendered:
+
+- CDK: the `cedarPolicyVariables` prop in
+  `packages/common/constructs/src/app/gateways/<name>/<name>.ts`
+- Terraform: the `query` of the `rendered_policies` data source in
+  `packages/common/terraform/src/app/gateways/<name>/<name>.tf`
+
+## Adding a new policy
+
+1. Create `policies/<my-policy>.cedar` alongside the existing files.
+2. Write Cedar rules — see the **Writing Policies** section of the
+   [AgentCore Gateway guide](https://awslabs.github.io/nx-plugin-for-aws/guides/agentcore-gateway/)
+   for valid patterns and validator gotchas.
+3. Re-synth / plan your infrastructure to deploy the new policy.
+
+Policy names are derived from file names: `my-policy.cedar` becomes the
+policy `MyPolicy` (plus a unique suffix, since policy names must be unique
+account-wide). Keep file names unique within this directory.
+
+## Further reading
+
+- [Cedar policy language reference](https://docs.cedarpolicy.com/)
+- [AgentCore policy semantics](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-understanding-cedar.html)
+- [AgentCore common policy patterns](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-common-patterns.html)

package/src/agentcore-gateway/files/cedar/policies/permit-all.cedar

@@ -0,0 +1,26 @@
+<%_ if (auth === 'cognito') { _%>
+// Default policy: permit any Cognito-authenticated caller.
+// The gateway's JWT authorizer already validates the token's user pool and
+// client, so any principal reaching policy evaluation is an authenticated
+// OAuth user. The PolicyEngine runs in ENFORCE mode (default-deny) — deleting
+// this file without a replacement permit denies every call. See
+// policies/README.md.
+
+permit (
+  principal is AgentCore::OAuthUser,
+  action,
+  resource == AgentCore::Gateway::"<%%= gatewayArn %>"
+);
+<%_ } else { _%>
+// Default policy: permit any IAM caller from the deploying AWS account.
+// The PolicyEngine runs in ENFORCE mode (default-deny) — deleting this file
+// without a replacement permit denies every call. See policies/README.md.
+
+permit (
+  principal is AgentCore::IamEntity,
+  action,
+  resource == AgentCore::Gateway::"<%%= gatewayArn %>"
+) when {
+  principal.id like "arn:aws:*::<%%= accountId %>:*"
+};
+<%_ } _%>