chore: Add PR's requested changes and additional AI comments

Co-authored-by: Copilot <copilot@github.com>

Author: matiasperrone-exo

app/Http/Controllers/OAuth2/OAuth2ProviderController.php

@@ -92,7 +92,7 @@ public function __construct
             new OA\Parameter(name: 'state', in: 'query', required: false, description: 'Opaque state parameter returned in the redirect', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'nonce', in: 'query', required: false, description: 'Nonce for ID token replay protection (OIDC)', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'response_mode', in: 'query', required: false, description: 'Response mode override', schema: new OA\Schema(type: 'string', enum: ['query', 'fragment', 'form_post', 'direct'])),
-            new OA\Parameter(name: 'prompt', in: 'query', required: false, description: 'Space-delimited user interaction prompts (OIDC)', schema: new OA\Schema(type: 'string', enum: ['none', 'login', 'consent', 'select_account'])),
+            new OA\Parameter(name: 'prompt', in: 'query', required: false, description: 'Space-delimited user interaction prompts (OIDC). Allowed tokens: none, login, consent, select_account. "none" cannot be combined with others. Example: "login consent"', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'login_hint', in: 'query', required: false, description: 'Hint about login identifier (OIDC)', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'display', in: 'query', required: false, description: 'UI display preference (OIDC)', schema: new OA\Schema(type: 'string', enum: ['page', 'popup', 'touch', 'wap', 'native'])),
             new OA\Parameter(name: 'max_age', in: 'query', required: false, description: 'Maximum authentication age in seconds (OIDC)', schema: new OA\Schema(type: 'integer')),
@@ -255,7 +255,6 @@ public function auth()
         summary: 'OAuth2 Token Endpoint',
         description: 'Issues access tokens. Supports authorization_code, client_credentials, password, refresh_token, and passwordless grant types.',
         tags: ['OAuth2 / OpenID Connect'],
-        security: [['OAuth2ProviderSecurity' => []]],
         requestBody: new OA\RequestBody(
             description: 'Token request parameters',
             required: true,
@@ -421,9 +420,19 @@ public function certs()
 
     #[OA\Get(
         path: '/.well-known/openid-configuration',
-        operationId: 'oauth2Discovery',
+        operationId: 'OpenIdDiscovery',
+        summary: 'OpenID Connect Discovery Endpoint',
+        description: 'Returns the OpenID Provider Configuration document per OpenID Connect Discovery 1.0.',
+        tags: ['OAuth2 / OpenID Connect'],
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'OpenID Connect Discovery document', content: new OA\JsonContent(ref: '#/components/schemas/OpenIDDiscoveryResponse')),
+        ]
+    )]
+    #[OA\Get(
+        path: '/oauth2/.well-known/openid-configuration',
+        operationId: 'OAclient_secretuth2OpenIdDiscovery',
         summary: 'OpenID Connect Discovery Endpoint',
-        description: 'Returns the OpenID Provider Configuration document per OpenID Connect Discovery 1.0. Also available at /oauth2/.well-known/openid-configuration.',
+        description: 'Returns the OpenID Provider Configuration document per OpenID Connect Discovery 1.0.',
         tags: ['OAuth2 / OpenID Connect'],
         responses: [
             new OA\Response(response: HttpResponse::HTTP_OK, description: 'OpenID Connect Discovery document', content: new OA\JsonContent(ref: '#/components/schemas/OpenIDDiscoveryResponse')),
@@ -457,6 +466,7 @@ public function checkSessionIFrame()
         summary: 'OpenID Connect End Session Endpoint (GET)',
         description: 'Initiates RP-Initiated Logout per OpenID Connect Session Management 1.0. Terminates the user session and optionally redirects to the post-logout URI.',
         tags: ['OAuth2 / OpenID Connect'],
+        security: [['OAuth2ProviderSecurity' => []]],
         parameters: [
             new OA\Parameter(name: 'client_id', in: 'query', required: true, description: 'OAuth2 client identifier', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'id_token_hint', in: 'query', required: false, description: 'Previously issued ID token', schema: new OA\Schema(type: 'string')),
@@ -475,6 +485,7 @@ public function checkSessionIFrame()
         summary: 'OpenID Connect End Session Endpoint (POST)',
         description: 'Initiates RP-Initiated Logout via POST. Same parameters as GET but sent as form data.',
         tags: ['OAuth2 / OpenID Connect'],
+        security: [['OAuth2ProviderSecurity' => []]],
         requestBody: new OA\RequestBody(
             description: 'End session parameters',
             required: true,

app/Swagger/OAuth2ProviderControllerSchemas.php

@@ -9,6 +9,7 @@
     title: 'OAuth2 Token Response',
     description: 'Successful token response per RFC 6749 §5.1',
     type: 'object',
+    required: ['access_token', 'token_type'],
     properties: [
         new OA\Property(property: 'access_token', type: 'string', description: 'The access token issued by the authorization server'),
         new OA\Property(property: 'token_type', type: 'string', description: 'The type of the token (typically Bearer)', example: 'Bearer'),
@@ -87,6 +88,7 @@ class OAuth2IntrospectionResponseSchema
     title: 'JSON Web Key Set',
     description: 'JWK Set document per RFC 7517',
     type: 'object',
+    required: ['keys'],
     properties: [
         new OA\Property(
             property: 'keys',
@@ -115,6 +117,7 @@ class JWKSResponseSchema
     title: 'OpenID Connect Discovery Document',
     description: 'OpenID Provider Configuration per OpenID Connect Discovery 1.0',
     type: 'object',
+    required: ['issuer', 'authorization_endpoint', 'token_endpoint', 'jwks_uri', 'response_types_supported', 'subject_types_supported', 'id_token_signing_alg_values_supported'],
     properties: [
         new OA\Property(property: 'issuer', type: 'string', format: 'uri', description: 'Issuer identifier URL'),
         new OA\Property(property: 'authorization_endpoint', type: 'string', format: 'uri', description: 'Authorization endpoint URL'),

app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php

@@ -18,7 +18,7 @@
         new OA\Property(property: 'state', type: 'string', description: 'Opaque state parameter'),
         new OA\Property(property: 'nonce', type: 'string', description: 'Nonce for ID token replay protection'),
         new OA\Property(property: 'response_mode', type: 'string', description: 'Response mode override', enum: ['query', 'fragment', 'form_post', 'direct']),
-        new OA\Property(property: 'prompt', type: 'string', description: 'User interaction prompts'),
+        new OA\Property(property: 'prompt', type: 'string', description: 'Space-delimited user interaction prompts (OIDC). Allowed tokens: none, login, consent, select_account. "none" cannot be combined with others. Example: "login consent"'),
         new OA\Property(property: 'login_hint', type: 'string', description: 'Login identifier hint'),
         new OA\Property(property: 'code_challenge', type: 'string', description: 'PKCE code challenge'),
         new OA\Property(property: 'code_challenge_method', type: 'string', description: 'PKCE challenge method', enum: ['plain', 'S256']),

app/Swagger/Requests/OAuth2TokenIntrospectionRequestSchema.php

@@ -13,7 +13,7 @@
     properties: [
         new OA\Property(property: 'token', type: 'string', description: 'The token to introspect'),
         new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
-        new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
+        new OA\Property(property: 'client_secret', type: 'string', format: 'password', description: 'Client secret (if not using HTTP Basic auth)'),
     ]
 )]
 class OAuth2TokenIntrospectionRequestSchema