feat(gateway): add Custom JWT inbound auth for MCP gateways

Add CUSTOM_JWT authorizer support to the gateway creation flow:
- TUI wizard for JWT configuration (discovery URL, audiences, clients,
  scopes, custom claim validations with string/string-array match types)
- CLI flags for non-interactive gateway creation with JWT auth
- Schema validation with OIDC discovery URL HTTPS enforcement,
  XOR validation for claim match values, and .strict() on config
- Fix gateway CfnOutput key prefix: CLI regex matches Gateway{Name}
  pattern (CDK fix in companion agentcore-cdk PR)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Constraint: OIDC discovery URL must be HTTPS per security review
Rejected: Allow HTTP discovery URLs | security risk for token validation
Directive: customClaims uses XOR between matchValue and matchValueStringList
Confidence: high
Scope-risk: moderate

Author: aidandaly24

integ-tests/tui/add-gateway-jwt.test.ts

@@ -0,0 +1,6 @@
+/**
+ * TUI integration test setup.
+ *
+ * This file is referenced by vitest.config.ts as a setupFile for the 'tui' project.
+ * It runs before each test file in integ-tests/tui/.
+ */

integ-tests/tui/setup.ts

@@ -52,7 +52,7 @@ export function parseGatewayOutputs(
   const gatewayNames = Object.keys(gatewaySpecs);
   const gatewayIdMap = new Map(gatewayNames.map(name => [toPascalId(name), name]));
 
-  // Match patterns: Gateway{Name}{Type}Output
+  // Match patterns: Gateway{Name}{Type}Output{Hash}
   const outputPattern = /^Gateway(.+?)(Id|Arn|Url)Output/;
 
   for (const [key, value] of Object.entries(outputs)) {

src/cli/cloudformation/outputs.ts

@@ -167,9 +167,9 @@ describe('add gateway command', () => {
           'client1',
           '--allowed-scopes',
           'scope1,scope2',
-          '--agent-client-id',
+          '--client-id',
           'agent-cid',
-          '--agent-client-secret',
+          '--client-secret',
           'agent-secret',
           '--json',
         ],

src/cli/commands/add/__tests__/add-gateway.test.ts

@@ -220,19 +220,24 @@ describe('validate', () => {
       expect(result.error?.includes('Invalid authorizer type')).toBeTruthy();
     });
 
-    // AC11: CUSTOM_JWT requires discoveryUrl and allowedClients (allowedAudience is optional)
+    // AC11: CUSTOM_JWT requires discoveryUrl; at least one of allowedAudience/allowedClients/allowedScopes
     it('returns error for CUSTOM_JWT missing required fields', () => {
-      const jwtFields: { field: keyof AddGatewayOptions; error: string }[] = [
-        { field: 'discoveryUrl', error: '--discovery-url is required for CUSTOM_JWT authorizer' },
-        { field: 'allowedClients', error: '--allowed-clients is required for CUSTOM_JWT authorizer' },
-      ];
+      // discoveryUrl is always required
+      const result = validateAddGatewayOptions({ ...validGatewayOptionsJwt, discoveryUrl: undefined });
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('--discovery-url is required for CUSTOM_JWT authorizer');
 
-      for (const { field, error } of jwtFields) {
-        const opts = { ...validGatewayOptionsJwt, [field]: undefined };
-        const result = validateAddGatewayOptions(opts);
-        expect(result.valid, `Should fail for missing ${String(field)}`).toBe(false);
-        expect(result.error).toBe(error);
-      }
+      // All three optional fields absent fails
+      const noneResult = validateAddGatewayOptions({
+        ...validGatewayOptionsJwt,
+        allowedAudience: undefined,
+        allowedClients: undefined,
+        allowedScopes: undefined,
+      });
+      expect(noneResult.valid).toBe(false);
+      expect(noneResult.error).toBe(
+        'At least one of --allowed-audience, --allowed-clients, --allowed-scopes, or --custom-claims must be provided for CUSTOM_JWT authorizer'
+      );
     });
 
     // AC11b: allowedAudience is optional
@@ -255,11 +260,86 @@ describe('validate', () => {
       expect(result.error?.includes('.well-known/openid-configuration')).toBeTruthy();
     });
 
-    // AC13: Empty comma-separated clients rejected (audience can be empty)
-    it('returns error for empty clients', () => {
-      const result = validateAddGatewayOptions({ ...validGatewayOptionsJwt, allowedClients: '  ,  ' });
+    // AC13: At least one of audience/clients/scopes must be non-empty
+    it('returns error when all of audience, clients, and scopes are empty', () => {
+      const result = validateAddGatewayOptions({
+        ...validGatewayOptionsJwt,
+        allowedAudience: '  ',
+        allowedClients: undefined,
+        allowedScopes: undefined,
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe(
+        'At least one of --allowed-audience, --allowed-clients, --allowed-scopes, or --custom-claims must be provided for CUSTOM_JWT authorizer'
+      );
+    });
+
+    // AC-claims1: --custom-claims with valid JSON passes validation
+    it('accepts valid --custom-claims JSON', () => {
+      const result = validateAddGatewayOptions({
+        ...validGatewayOptionsJwt,
+        customClaims: JSON.stringify([
+          {
+            inboundTokenClaimName: 'dept',
+            inboundTokenClaimValueType: 'STRING',
+            authorizingClaimMatchValue: {
+              claimMatchOperator: 'EQUALS',
+              claimMatchValue: { matchValueString: 'engineering' },
+            },
+          },
+        ]),
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    // AC-claims2: --custom-claims alone satisfies the "at least one constraint" check
+    it('allows CUSTOM_JWT with only --custom-claims (no audience/clients/scopes)', () => {
+      const result = validateAddGatewayOptions({
+        name: 'test-gw',
+        authorizerType: 'CUSTOM_JWT',
+        discoveryUrl: 'https://example.com/.well-known/openid-configuration',
+        customClaims: JSON.stringify([
+          {
+            inboundTokenClaimName: 'role',
+            inboundTokenClaimValueType: 'STRING_ARRAY',
+            authorizingClaimMatchValue: {
+              claimMatchOperator: 'CONTAINS_ANY',
+              claimMatchValue: { matchValueStringList: ['admin'] },
+            },
+          },
+        ]),
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    // AC-claims3: --custom-claims with invalid JSON fails
+    it('returns error for --custom-claims with invalid JSON', () => {
+      const result = validateAddGatewayOptions({
+        ...validGatewayOptionsJwt,
+        customClaims: 'not json',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('--custom-claims must be valid JSON');
+    });
+
+    // AC-claims4: --custom-claims with empty array fails
+    it('returns error for --custom-claims with empty array', () => {
+      const result = validateAddGatewayOptions({
+        ...validGatewayOptionsJwt,
+        customClaims: '[]',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toBe('--custom-claims must be a non-empty JSON array');
+    });
+
+    // AC-claims5: --custom-claims with invalid claim structure fails
+    it('returns error for --custom-claims with invalid claim structure', () => {
+      const result = validateAddGatewayOptions({
+        ...validGatewayOptionsJwt,
+        customClaims: JSON.stringify([{ badField: 'value' }]),
+      });
       expect(result.valid).toBe(false);
-      expect(result.error).toBe('At least one client value is required');
+      expect(result.error).toContain('Invalid custom claim at index 0');
     });
 
     // AC14: Valid options pass
@@ -268,42 +348,42 @@ describe('validate', () => {
       expect(validateAddGatewayOptions(validGatewayOptionsJwt)).toEqual({ valid: true });
     });
 
-    // AC15: agentClientId and agentClientSecret must be provided together
-    it('returns error when agentClientId provided without agentClientSecret', () => {
+    // AC15: clientId and clientSecret must be provided together
+    it('returns error when clientId provided without clientSecret', () => {
       const result = validateAddGatewayOptions({
         ...validGatewayOptionsJwt,
-        agentClientId: 'my-client-id',
+        clientId: 'my-client-id',
       });
       expect(result.valid).toBe(false);
-      expect(result.error).toBe('Both --agent-client-id and --agent-client-secret must be provided together');
+      expect(result.error).toBe('Both --client-id and --client-secret must be provided together');
     });
 
-    it('returns error when agentClientSecret provided without agentClientId', () => {
+    it('returns error when clientSecret provided without clientId', () => {
       const result = validateAddGatewayOptions({
         ...validGatewayOptionsJwt,
-        agentClientSecret: 'my-secret',
+        clientSecret: 'my-secret',
       });
       expect(result.valid).toBe(false);
-      expect(result.error).toBe('Both --agent-client-id and --agent-client-secret must be provided together');
+      expect(result.error).toBe('Both --client-id and --client-secret must be provided together');
     });
 
-    // AC16: agent credentials only valid with CUSTOM_JWT
-    it('returns error when agent credentials used with non-CUSTOM_JWT authorizer', () => {
+    // AC16: OAuth client credentials only valid with CUSTOM_JWT
+    it('returns error when OAuth client credentials used with non-CUSTOM_JWT authorizer', () => {
       const result = validateAddGatewayOptions({
         ...validGatewayOptionsNone,
-        agentClientId: 'my-client-id',
-        agentClientSecret: 'my-secret',
+        clientId: 'my-client-id',
+        clientSecret: 'my-secret',
       });
       expect(result.valid).toBe(false);
-      expect(result.error).toBe('Agent OAuth credentials are only valid with CUSTOM_JWT authorizer');
+      expect(result.error).toBe('OAuth client credentials are only valid with CUSTOM_JWT authorizer');
     });
 
-    // AC17: valid CUSTOM_JWT with agent credentials passes
-    it('passes for CUSTOM_JWT with agent credentials', () => {
+    // AC17: valid CUSTOM_JWT with OAuth client credentials passes
+    it('passes for CUSTOM_JWT with OAuth client credentials', () => {
       const result = validateAddGatewayOptions({
         ...validGatewayOptionsJwt,
-        agentClientId: 'my-client-id',
-        agentClientSecret: 'my-secret',
+        clientId: 'my-client-id',
+        clientSecret: 'my-secret',
         allowedScopes: 'scope1,scope2',
       });
       expect(result.valid).toBe(true);

src/cli/commands/add/__tests__/validate.test.ts

@@ -34,8 +34,9 @@ export interface AddGatewayOptions {
   allowedAudience?: string;
   allowedClients?: string;
   allowedScopes?: string;
-  agentClientId?: string;
-  agentClientSecret?: string;
+  customClaims?: string;
+  clientId?: string;
+  clientSecret?: string;
   agents?: string;
   semanticSearch?: boolean;
   exceptionLevel?: string;

src/cli/commands/add/types.ts

@@ -2,6 +2,7 @@ import { ConfigIO, findConfigRoot } from '../../../lib';
 import {
   AgentNameSchema,
   BuildTypeSchema,
+  CustomClaimValidationSchema,
   GatewayExceptionLevelSchema,
   GatewayNameSchema,
   ModelProviderSchema,
@@ -230,7 +231,10 @@ export function validateAddGatewayOptions(options: AddGatewayOptions): Validatio
     }
 
     try {
-      new URL(options.discoveryUrl);
+      const url = new URL(options.discoveryUrl);
+      if (url.protocol !== 'https:') {
+        return { valid: false, error: 'Discovery URL must use HTTPS' };
+      }
     } catch {
       return { valid: false, error: 'Discovery URL must be a valid URL' };
     }
@@ -239,30 +243,49 @@ export function validateAddGatewayOptions(options: AddGatewayOptions): Validatio
       return { valid: false, error: `Discovery URL must end with ${OIDC_WELL_KNOWN_SUFFIX}` };
     }
 
-    // allowedAudience is optional - empty means no audience validation
-
-    if (!options.allowedClients) {
-      return { valid: false, error: '--allowed-clients is required for CUSTOM_JWT authorizer' };
+    // Validate custom claims JSON if provided
+    if (options.customClaims) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(options.customClaims);
+      } catch {
+        return { valid: false, error: '--custom-claims must be valid JSON' };
+      }
+      if (!Array.isArray(parsed) || parsed.length === 0) {
+        return { valid: false, error: '--custom-claims must be a non-empty JSON array' };
+      }
+      for (const [i, entry] of parsed.entries()) {
+        const result = CustomClaimValidationSchema.safeParse(entry);
+        if (!result.success) {
+          return { valid: false, error: `Invalid custom claim at index ${i}: ${result.error.issues[0]?.message}` };
+        }
+      }
     }
 
-    const clients = options.allowedClients
-      .split(',')
-      .map(s => s.trim())
-      .filter(Boolean);
-    if (clients.length === 0) {
-      return { valid: false, error: 'At least one client value is required' };
+    // allowedAudience, allowedClients, allowedScopes, customClaims are all optional individually,
+    // but at least one must be provided
+    const hasAudience = !!options.allowedAudience?.trim();
+    const hasClients = !!options.allowedClients?.trim();
+    const hasScopes = !!options.allowedScopes?.trim();
+    const hasClaims = !!options.customClaims?.trim();
+    if (!hasAudience && !hasClients && !hasScopes && !hasClaims) {
+      return {
+        valid: false,
+        error:
+          'At least one of --allowed-audience, --allowed-clients, --allowed-scopes, or --custom-claims must be provided for CUSTOM_JWT authorizer',
+      };
     }
   }
 
-  // Validate agent OAuth credentials
-  if (options.agentClientId && !options.agentClientSecret) {
-    return { valid: false, error: 'Both --agent-client-id and --agent-client-secret must be provided together' };
+  // Validate OAuth client credentials
+  if (options.clientId && !options.clientSecret) {
+    return { valid: false, error: 'Both --client-id and --client-secret must be provided together' };
   }
-  if (options.agentClientSecret && !options.agentClientId) {
-    return { valid: false, error: 'Both --agent-client-id and --agent-client-secret must be provided together' };
+  if (options.clientSecret && !options.clientId) {
+    return { valid: false, error: 'Both --client-id and --client-secret must be provided together' };
   }
-  if (options.agentClientId && options.authorizerType !== 'CUSTOM_JWT') {
-    return { valid: false, error: 'Agent OAuth credentials are only valid with CUSTOM_JWT authorizer' };
+  if (options.clientId && options.authorizerType !== 'CUSTOM_JWT') {
+    return { valid: false, error: 'OAuth client credentials are only valid with CUSTOM_JWT authorizer' };
   }
 
   // Validate exception level if provided