feat: add PolicyEngineConfiguration support for gateways

Author: Hweinstock

package-lock.json

@@ -16,14 +16,13 @@
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/node": "^24.10.1",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.2.5",
     "aws-cdk": "2.1100.1",
+    "jest": "^29.7.0",
     "prettier": "^3.4.2",
+    "ts-jest": "^29.2.5",
     "typescript": "~5.9.3"
   },
   "dependencies": {
-    "@aws/agentcore-cdk": "^0.1.0-alpha.1",
     "aws-cdk-lib": "2.243.0",
     "constructs": "^10.0.0"
   }

src/assets/cdk/package-lock.json

@@ -39,6 +39,8 @@ export interface AddGatewayOptions {
   agents?: string;
   semanticSearch?: boolean;
   exceptionLevel?: string;
+  policyEngine?: string;
+  policyEngineMode?: string;
   json?: boolean;
 }
 

src/assets/cdk/package.json

@@ -273,6 +273,17 @@ export function validateAddGatewayOptions(options: AddGatewayOptions): Validatio
     }
   }
 
+  // Validate policy engine options
+  if (options.policyEngine && !options.policyEngineMode) {
+    return { valid: false, error: '--policy-engine-mode is required when --policy-engine is specified' };
+  }
+  if (options.policyEngineMode && !options.policyEngine) {
+    return { valid: false, error: '--policy-engine is required when --policy-engine-mode is specified' };
+  }
+  if (options.policyEngineMode && !['LOG_ONLY', 'ENFORCE'].includes(options.policyEngineMode)) {
+    return { valid: false, error: `Invalid policy engine mode: ${options.policyEngineMode}. Use LOG_ONLY or ENFORCE` };
+  }
+
   return { valid: true };
 }
 

src/cli/commands/add/types.ts

@@ -28,6 +28,8 @@ export interface AddGatewayOptions {
   agents?: string;
   enableSemanticSearch?: boolean;
   exceptionLevel?: string;
+  policyEngine?: string;
+  policyEngineMode?: string;
 }
 
 /**
@@ -160,6 +162,8 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       .option('--agents <agents>', 'Comma-separated agent names')
       .option('--no-semantic-search', 'Disable semantic search for tool discovery')
       .option('--exception-level <level>', 'Exception verbosity level', 'NONE')
+      .option('--policy-engine <name>', 'Policy engine name for Cedar-based authorization')
+      .option('--policy-engine-mode <mode>', 'Policy engine mode: LOG_ONLY or ENFORCE')
       .option('--json', 'Output as JSON')
       .action(async (rawOptions: Record<string, string | boolean | undefined>) => {
         const cliOptions = rawOptions as unknown as CLIAddGatewayOptions;
@@ -192,6 +196,8 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
             agents: cliOptions.agents,
             enableSemanticSearch: cliOptions.semanticSearch !== false,
             exceptionLevel: cliOptions.exceptionLevel,
+            policyEngine: cliOptions.policyEngine,
+            policyEngineMode: cliOptions.policyEngineMode,
           });
 
           if (cliOptions.json) {
@@ -290,6 +296,10 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       jwtConfig: undefined,
       enableSemanticSearch: options.enableSemanticSearch ?? true,
       exceptionLevel: options.exceptionLevel === 'DEBUG' ? 'DEBUG' : 'NONE',
+      policyEngineConfiguration:
+        options.policyEngine && options.policyEngineMode
+          ? { policyEngineName: options.policyEngine, mode: options.policyEngineMode as 'LOG_ONLY' | 'ENFORCE' }
+          : undefined,
     };
 
     if (options.authorizerType === 'CUSTOM_JWT' && options.discoveryUrl) {
@@ -358,6 +368,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       authorizerConfiguration: this.buildAuthorizerConfiguration(config),
       enableSemanticSearch: config.enableSemanticSearch,
       exceptionLevel: config.exceptionLevel,
+      policyEngineConfiguration: config.policyEngineConfiguration,
     };
 
     mcpSpec.agentCoreGateways.push(gateway);

src/cli/commands/add/validate.ts

@@ -53,6 +53,21 @@ export class PolicyEnginePrimitive extends BasePrimitive<AddPolicyEngineOptions,
       project.policyEngines.splice(index, 1);
       await this.writeProjectSpec(project);
 
+      // Clean up any gateway references to this engine in mcp.json
+      if (this.configIO.configExists('mcp')) {
+        const mcpSpec = await this.configIO.readMcpSpec();
+        let changed = false;
+        for (const gw of mcpSpec.agentCoreGateways) {
+          if (gw.policyEngineConfiguration?.policyEngineName === engineName) {
+            delete gw.policyEngineConfiguration;
+            changed = true;
+          }
+        }
+        if (changed) {
+          await this.configIO.writeMcpSpec(mcpSpec);
+        }
+      }
+
       return { success: true };
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Unknown error';
@@ -84,6 +99,32 @@ export class PolicyEnginePrimitive extends BasePrimitive<AddPolicyEngineOptions,
       after: afterSpec,
     });
 
+    // Show mcp.json changes if any gateways reference this engine
+    if (this.configIO.configExists('mcp')) {
+      const mcpSpec = await this.configIO.readMcpSpec();
+      const affectedGateways = mcpSpec.agentCoreGateways.filter(
+        gw => gw.policyEngineConfiguration?.policyEngineName === engineName
+      );
+      if (affectedGateways.length > 0) {
+        summary.push(
+          `Note: ${affectedGateways.length} gateway(s) referencing this engine will have policyEngineConfiguration removed`
+        );
+        const afterMcpSpec = {
+          ...mcpSpec,
+          agentCoreGateways: mcpSpec.agentCoreGateways.map(gw =>
+            gw.policyEngineConfiguration?.policyEngineName === engineName
+              ? { ...gw, policyEngineConfiguration: undefined }
+              : gw
+          ),
+        };
+        schemaChanges.push({
+          file: 'agentcore/mcp.json',
+          before: mcpSpec,
+          after: afterMcpSpec,
+        });
+      }
+    }
+
     return { summary, directoriesToDelete: [], schemaChanges };
   }
 

src/cli/primitives/GatewayPrimitive.ts

@@ -2,6 +2,7 @@ import type {
   ApiGatewayHttpMethod,
   GatewayAuthorizerType,
   GatewayExceptionLevel,
+  GatewayPolicyEngineConfiguration,
   GatewayTargetType,
   NodeRuntime,
   PythonRuntime,
@@ -36,6 +37,8 @@ export interface AddGatewayConfig {
   enableSemanticSearch: boolean;
   /** Exception verbosity level for the gateway */
   exceptionLevel: GatewayExceptionLevel;
+  /** Policy engine configuration for Cedar-based authorization */
+  policyEngineConfiguration?: GatewayPolicyEngineConfiguration;
 }
 
 /** Item ID for the semantic search toggle in the advanced config pane. */

src/cli/primitives/PolicyEnginePrimitive.ts

@@ -593,6 +593,21 @@ export type AgentCoreGatewayTarget = z.infer<typeof AgentCoreGatewayTargetSchema
 export const GatewayExceptionLevelSchema = z.enum(['NONE', 'DEBUG']);
 export type GatewayExceptionLevel = z.infer<typeof GatewayExceptionLevelSchema>;
 
+// ============================================================================
+// Gateway Policy Engine Configuration
+// ============================================================================
+
+export const PolicyEngineModeSchema = z.enum(['LOG_ONLY', 'ENFORCE']);
+export type PolicyEngineMode = z.infer<typeof PolicyEngineModeSchema>;
+
+export const GatewayPolicyEngineConfigurationSchema = z
+  .object({
+    policyEngineName: z.string().min(1),
+    mode: PolicyEngineModeSchema,
+  })
+  .strict();
+export type GatewayPolicyEngineConfiguration = z.infer<typeof GatewayPolicyEngineConfigurationSchema>;
+
 // ============================================================================
 // Gateway
 // ============================================================================
@@ -614,6 +629,8 @@ export const AgentCoreGatewaySchema = z
     enableSemanticSearch: z.boolean().default(true),
     /** Exception verbosity level. 'NONE' = generic errors (default), 'DEBUG' = verbose errors. */
     exceptionLevel: GatewayExceptionLevelSchema.default('NONE'),
+    /** Policy engine configuration for Cedar-based authorization of tool calls. */
+    policyEngineConfiguration: GatewayPolicyEngineConfigurationSchema.optional(),
   })
   .strict()
   .refine(