feat(gateway): add custom claims validation and TUI wizard for JWT auth

Add custom JWT claims validation support and a full TUI wizard flow
for configuring Custom JWT gateway authorization.

Schema:
- Add ClaimMatchOperator, ClaimMatchValue, InboundTokenClaimValueType,
  and CustomClaimValidation schemas with strict validation
- Add customClaims to CustomJwtAuthorizerConfigSchema and deployed-state
- Add --custom-claims CLI flag with JSON parsing and validation

TUI Wizard:
- Expand JWT config flow with custom claims manager (add/edit/done)
- Add claim name, operator, value, and value type sub-steps
- Show human-readable claim summary in confirm review
- Make client credentials optional (skip with empty Enter)

Testing:
- Add AddGatewayJwtConfig.test.tsx — full TUI component tests
- Add finishJwtConfig.test.ts — unit tests for config assembly
- Extend useAddGatewayWizard.test.tsx with JWT + custom claims flows
- Add GatewayPrimitive.test.ts for custom claims round-trip
- Extend validate.test.ts with custom claims validation cases
- Add TUI integration test (add-gateway-jwt.test.ts)

Constraint: Stacked on fix/inbound-auth-hardening (aws#598)
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

@@ -218,40 +218,29 @@ describe('validate', () => {
       expect(result.error?.includes('Invalid authorizer type')).toBeTruthy();
     });
 
-    // AC11: CUSTOM_JWT requires discoveryUrl
-    it('returns error for CUSTOM_JWT missing discoveryUrl', () => {
-      const opts = { ...validGatewayOptionsJwt, discoveryUrl: undefined };
-      const result = validateAddGatewayOptions(opts);
+    // AC11: CUSTOM_JWT requires discoveryUrl; at least one of allowedAudience/allowedClients/allowedScopes
+    it('returns error for CUSTOM_JWT missing required fields', () => {
+      // 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');
-    });
 
-    // AC11b: at least one of audience/clients/scopes required
-    it('returns error when all of audience, clients, and scopes are missing', () => {
-      const opts = {
+      // All three optional fields absent fails
+      const noneResult = validateAddGatewayOptions({
         ...validGatewayOptionsJwt,
         allowedAudience: undefined,
         allowedClients: undefined,
         allowedScopes: undefined,
-      };
-      const result = validateAddGatewayOptions(opts);
-      expect(result.valid).toBe(false);
-      expect(result.error).toContain('At least one of');
-    });
-
-    it('allows CUSTOM_JWT with only allowedScopes', () => {
-      const opts = {
-        ...validGatewayOptionsJwt,
-        allowedAudience: undefined,
-        allowedClients: undefined,
-        allowedScopes: 'scope1',
-      };
-      const result = validateAddGatewayOptions(opts);
-      expect(result.valid).toBe(true);
+      });
+      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'
+      );
     });
 
-    it('allows CUSTOM_JWT with only allowedAudience', () => {
-      const opts = { ...validGatewayOptionsJwt, allowedClients: undefined, allowedScopes: undefined };
+    // AC11b: allowedAudience is optional
+    it('allows CUSTOM_JWT without allowedAudience', () => {
+      const opts = { ...validGatewayOptionsJwt, allowedAudience: undefined };
       const result = validateAddGatewayOptions(opts);
       expect(result.valid).toBe(true);
     });
@@ -269,21 +258,88 @@ describe('validate', () => {
       expect(result.error?.includes('.well-known/openid-configuration')).toBeTruthy();
     });
 
-    it('returns error for HTTP discoveryUrl (HTTPS required)', () => {
+    // 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,
-        discoveryUrl: 'http://example.com/.well-known/openid-configuration',
+        allowedAudience: '  ',
+        allowedClients: undefined,
+        allowedScopes: undefined,
       });
       expect(result.valid).toBe(false);
-      expect(result.error).toBe('Discovery URL must use HTTPS');
+      expect(result.error).toBe(
+        'At least one of --allowed-audience, --allowed-clients, --allowed-scopes, or --custom-claims must be provided for CUSTOM_JWT authorizer'
+      );
     });
 
-    it('allows CUSTOM_JWT with only allowedClients', () => {
-      const opts = { ...validGatewayOptionsJwt, allowedAudience: undefined, allowedScopes: undefined };
-      const result = validateAddGatewayOptions(opts);
+    // 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).toContain('Invalid custom claim at index 0');
+    });
+
     // AC14: Valid options pass
     it('passes for valid options', () => {
       expect(validateAddGatewayOptions(validGatewayOptionsNone)).toEqual({ valid: true });
@@ -309,8 +365,8 @@ describe('validate', () => {
       expect(result.error).toBe('Both --client-id and --client-secret must be provided together');
     });
 
-    // AC16: OAuth credentials only valid with CUSTOM_JWT
-    it('returns error when OAuth 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,
         clientId: 'my-client-id',
@@ -320,8 +376,8 @@ describe('validate', () => {
       expect(result.error).toBe('OAuth client credentials are only valid with CUSTOM_JWT authorizer');
     });
 
-    // AC17: valid CUSTOM_JWT with OAuth credentials passes
-    it('passes for CUSTOM_JWT with OAuth credentials', () => {
+    // AC17: valid CUSTOM_JWT with OAuth client credentials passes
+    it('passes for CUSTOM_JWT with OAuth client credentials', () => {
       const result = validateAddGatewayOptions({
         ...validGatewayOptionsJwt,
         clientId: 'my-client-id',

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

@@ -37,6 +37,7 @@ export interface AddGatewayOptions {
   allowedAudience?: string;
   allowedClients?: string;
   allowedScopes?: string;
+  customClaims?: string;
   clientId?: string;
   clientSecret?: string;
   agents?: string;

src/cli/commands/add/types.ts

@@ -2,6 +2,7 @@ import { ConfigIO, findConfigRoot } from '../../../lib';
 import {
   AgentNameSchema,
   BuildTypeSchema,
+  CustomClaimValidationSchema,
   GatewayExceptionLevelSchema,
   GatewayNameSchema,
   ModelProviderSchema,
@@ -275,16 +276,36 @@ export function validateAddGatewayOptions(options: AddGatewayOptions): Validatio
       return { valid: false, error: `Discovery URL must end with ${OIDC_WELL_KNOWN_SUFFIX}` };
     }
 
-    // allowedAudience, allowedClients, allowedScopes are all optional individually,
+    // 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}` };
+        }
+      }
+    }
+
+    // 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();
-    if (!hasAudience && !hasClients && !hasScopes) {
+    const hasClaims = !!options.customClaims?.trim();
+    if (!hasAudience && !hasClients && !hasScopes && !hasClaims) {
       return {
         valid: false,
         error:
-          'At least one of --allowed-audience, --allowed-clients, or --allowed-scopes must be provided for CUSTOM_JWT authorizer',
+          'At least one of --allowed-audience, --allowed-clients, --allowed-scopes, or --custom-claims must be provided for CUSTOM_JWT authorizer',
       };
     }
   }

src/cli/commands/add/validate.ts

@@ -4,6 +4,7 @@ import type {
   AgentCoreGatewayTarget,
   AgentCoreMcpSpec,
   AgentCoreProjectSpec,
+  CustomClaimValidation,
   GatewayAuthorizerType,
 } from '../../schema';
 import { AgentCoreGatewaySchema, PolicyEngineModeSchema } from '../../schema';
@@ -29,6 +30,7 @@ export interface AddGatewayOptions {
   allowedAudience?: string;
   allowedClients?: string;
   allowedScopes?: string;
+  customClaims?: CustomClaimValidation[];
   clientId?: string;
   clientSecret?: string;
   agents?: string;
@@ -164,6 +166,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
       .option('--allowed-audience <audience>', 'Comma-separated allowed audiences (for CUSTOM_JWT)')
       .option('--allowed-clients <clients>', 'Comma-separated allowed client IDs (for CUSTOM_JWT)')
       .option('--allowed-scopes <scopes>', 'Comma-separated allowed scopes (for CUSTOM_JWT)')
+      .option('--custom-claims <json>', 'Custom claim validations as JSON array (for CUSTOM_JWT)')
       .option('--client-id <id>', 'OAuth client ID for gateway bearer token')
       .option('--client-secret <secret>', 'OAuth client secret')
       .option('--agents <agents>', 'Comma-separated agent names')
@@ -190,6 +193,11 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
             process.exit(1);
           }
 
+          // Parse custom claims JSON if provided (already validated)
+          const parsedCustomClaims = cliOptions.customClaims
+            ? (JSON.parse(cliOptions.customClaims) as CustomClaimValidation[])
+            : undefined;
+
           const result = await this.add({
             name: cliOptions.name!,
             description: cliOptions.description,
@@ -198,6 +206,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
             allowedAudience: cliOptions.allowedAudience,
             allowedClients: cliOptions.allowedClients,
             allowedScopes: cliOptions.allowedScopes,
+            customClaims: parsedCustomClaims,
             clientId: cliOptions.clientId,
             clientSecret: cliOptions.clientSecret,
             agents: cliOptions.agents,
@@ -334,6 +343,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
         ...(allowedAudience?.length ? { allowedAudience } : {}),
         ...(allowedClients?.length ? { allowedClients } : {}),
         ...(allowedScopes?.length ? { allowedScopes } : {}),
+        ...(options.customClaims?.length ? { customClaims: options.customClaims } : {}),
         ...(options.clientId ? { clientId: options.clientId } : {}),
         ...(options.clientSecret ? { clientSecret: options.clientSecret } : {}),
       };
@@ -434,6 +444,7 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
         ...(config.jwtConfig.allowedAudience?.length ? { allowedAudience: config.jwtConfig.allowedAudience } : {}),
         ...(config.jwtConfig.allowedClients?.length ? { allowedClients: config.jwtConfig.allowedClients } : {}),
         ...(config.jwtConfig.allowedScopes?.length ? { allowedScopes: config.jwtConfig.allowedScopes } : {}),
+        ...(config.jwtConfig.customClaims?.length ? { customClaims: config.jwtConfig.customClaims } : {}),
       },
     };
   }

src/cli/primitives/GatewayPrimitive.ts

@@ -51,6 +51,78 @@ describe('GatewayPrimitive', () => {
     primitive = new GatewayPrimitive();
   });
 
+  describe('customClaims pipeline', () => {
+    const SAMPLE_CLAIMS = [
+      {
+        inboundTokenClaimName: 'department',
+        inboundTokenClaimValueType: 'STRING_ARRAY' as const,
+        authorizingClaimMatchValue: {
+          claimMatchOperator: 'CONTAINS_ANY' as const,
+          claimMatchValue: { matchValueStringList: ['engineering', 'sales'] },
+        },
+      },
+    ];
+
+    it('custom claims from TUI flow are written to authorizerConfiguration', async () => {
+      await primitive.add({
+        name: 'jwt-gw',
+        authorizerType: 'CUSTOM_JWT',
+        discoveryUrl: 'https://example.com/.well-known/openid-configuration',
+        allowedAudience: 'aud1',
+        customClaims: SAMPLE_CLAIMS,
+      });
+
+      const gw = getWrittenGateway();
+      expect(gw.authorizerConfiguration?.customJwtAuthorizer).toBeDefined();
+      expect(gw.authorizerConfiguration!.customJwtAuthorizer!.customClaims).toEqual(SAMPLE_CLAIMS);
+    });
+
+    it('custom claims are preserved alongside audience and clients', async () => {
+      await primitive.add({
+        name: 'jwt-gw',
+        authorizerType: 'CUSTOM_JWT',
+        discoveryUrl: 'https://example.com/.well-known/openid-configuration',
+        allowedAudience: 'aud1,aud2',
+        allowedClients: 'client1',
+        customClaims: SAMPLE_CLAIMS,
+      });
+
+      const gw = getWrittenGateway();
+      const jwtConfig = gw.authorizerConfiguration!.customJwtAuthorizer!;
+      expect(jwtConfig.allowedAudience).toEqual(['aud1', 'aud2']);
+      expect(jwtConfig.allowedClients).toEqual(['client1']);
+      expect(jwtConfig.customClaims).toEqual(SAMPLE_CLAIMS);
+    });
+
+    it('omits customClaims from authorizerConfiguration when not provided', async () => {
+      await primitive.add({
+        name: 'jwt-gw',
+        authorizerType: 'CUSTOM_JWT',
+        discoveryUrl: 'https://example.com/.well-known/openid-configuration',
+        allowedAudience: 'aud1',
+      });
+
+      const gw = getWrittenGateway();
+      expect(gw.authorizerConfiguration!.customJwtAuthorizer!.customClaims).toBeUndefined();
+    });
+
+    it('custom claims only (no audience/clients/scopes) produces valid config', async () => {
+      await primitive.add({
+        name: 'jwt-gw',
+        authorizerType: 'CUSTOM_JWT',
+        discoveryUrl: 'https://example.com/.well-known/openid-configuration',
+        customClaims: SAMPLE_CLAIMS,
+      });
+
+      const gw = getWrittenGateway();
+      const jwtConfig = gw.authorizerConfiguration!.customJwtAuthorizer!;
+      expect(jwtConfig.allowedAudience).toBeUndefined();
+      expect(jwtConfig.allowedClients).toBeUndefined();
+      expect(jwtConfig.allowedScopes).toBeUndefined();
+      expect(jwtConfig.customClaims).toEqual(SAMPLE_CLAIMS);
+    });
+  });
+
   describe('exceptionLevel', () => {
     it('defaults to exceptionLevel NONE', async () => {
       await primitive.add({ name: 'test-gw', authorizerType: 'NONE' });

src/cli/primitives/__tests__/GatewayPrimitive.test.ts

@@ -31,6 +31,7 @@ export function useCreateGateway() {
         allowedAudience: config.jwtConfig?.allowedAudience?.join(','),
         allowedClients: config.jwtConfig?.allowedClients?.join(','),
         allowedScopes: config.jwtConfig?.allowedScopes?.join(','),
+        customClaims: config.jwtConfig?.customClaims,
         clientId: config.jwtConfig?.clientId,
         clientSecret: config.jwtConfig?.clientSecret,
         enableSemanticSearch: config.enableSemanticSearch,