fix: add RFC 7591 error codes, Content-Type validation, and docblock safety warning

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: chr-hertel

src/Exception/ClientRegistrationException.php

@@ -13,4 +13,11 @@
 
 final class ClientRegistrationException extends \RuntimeException implements ExceptionInterface
 {
+    public function __construct(
+        string $message,
+        public readonly string $errorCode = 'invalid_client_metadata',
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct($message, 0, $previous);
+    }
 }

src/Server/Transport/Http/Middleware/ClientRegistrationMiddleware.php

@@ -69,6 +69,14 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
 
     private function handleRegistration(ServerRequestInterface $request): ResponseInterface
     {
+        $contentType = $request->getHeaderLine('Content-Type');
+        if (!str_starts_with($contentType, 'application/json')) {
+            return $this->jsonResponse(400, [
+                'error' => 'invalid_client_metadata',
+                'error_description' => 'Content-Type must be application/json.',
+            ], ['Cache-Control' => 'no-store']);
+        }
+
         $body = $request->getBody()->__toString();
 
         try {
@@ -95,7 +103,7 @@ private function handleRegistration(ServerRequestInterface $request): ResponseIn
             $result = $this->registrar->register($data);
         } catch (ClientRegistrationException $e) {
             return $this->jsonResponse(400, [
-                'error' => 'invalid_client_metadata',
+                'error' => $e->errorCode,
                 'error_description' => $e->getMessage(),
             ], ['Cache-Control' => 'no-store']);
         }

src/Server/Transport/Http/OAuth/ClientRegistrarInterface.php

@@ -36,7 +36,9 @@ interface ClientRegistrarInterface
      *
      * @return array<string, mixed> Registration response including client_id and optional client_secret
      *
-     * @throws ClientRegistrationException If registration fails (e.g. invalid metadata, storage error)
+     * @throws ClientRegistrationException If registration fails (e.g. invalid metadata, storage error).
+     *                                     The exception message is returned to the client as error_description —
+     *                                     do not include internal details (database errors, stack traces, etc.).
      */
     public function register(array $registrationRequest): array;
 }

tests/Unit/Server/Transport/Http/Middleware/ClientRegistrationMiddlewareTest.php

@@ -44,6 +44,7 @@ public function testRegistrationSuccess(): void
         $middleware = $this->createMiddleware($registrar);
 
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream(json_encode(['redirect_uris' => ['https://example.com/callback']])));
 
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
@@ -65,6 +66,7 @@ public function testRegistrationWithInvalidJson(): void
         $middleware = $this->createMiddleware($registrar);
 
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream('not json'));
 
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
@@ -84,6 +86,7 @@ public function testRegistrationWithJsonArrayReturns400(): void
         $middleware = $this->createMiddleware($registrar);
 
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream('["not","an","object"]'));
 
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
@@ -103,6 +106,7 @@ public function testRegistrationWithEmptyJsonArrayReturns400(): void
         $middleware = $this->createMiddleware($registrar);
 
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream('[]'));
 
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
@@ -138,6 +142,7 @@ public function testRegistrationWithNestedObjectsPassesAssociativeArrays(): void
         ]);
 
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream($body));
 
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
@@ -153,12 +158,14 @@ public function testRegistrationErrorResponsesIncludeCacheControl(): void
 
         // Invalid JSON
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream('not json'));
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
         $this->assertSame('no-store', $response->getHeaderLine('Cache-Control'));
 
         // JSON array (not object)
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream('["array"]'));
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
         $this->assertSame('no-store', $response->getHeaderLine('Cache-Control'));
@@ -175,6 +182,7 @@ public function testRegistrationWithRegistrarException(): void
         $middleware = $this->createMiddleware($registrar);
 
         $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
             ->withBody($this->factory->createStream('{}'));
 
         $response = $middleware->process($request, $this->createPassthroughHandler(404));
@@ -187,6 +195,49 @@ public function testRegistrationWithRegistrarException(): void
         $this->assertSame('redirect_uris is required', $payload['error_description']);
     }
 
+    #[TestDox('POST /register without application/json Content-Type returns 400')]
+    public function testRegistrationRejectsNonJsonContentType(): void
+    {
+        $registrar = $this->createStub(ClientRegistrarInterface::class);
+        $middleware = $this->createMiddleware($registrar);
+
+        $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/x-www-form-urlencoded')
+            ->withBody($this->factory->createStream('key=value'));
+
+        $response = $middleware->process($request, $this->createPassthroughHandler(404));
+
+        $this->assertSame(400, $response->getStatusCode());
+        $this->assertSame('no-store', $response->getHeaderLine('Cache-Control'));
+
+        $payload = json_decode($response->getBody()->__toString(), true, 512, \JSON_THROW_ON_ERROR);
+        $this->assertSame('invalid_client_metadata', $payload['error']);
+        $this->assertSame('Content-Type must be application/json.', $payload['error_description']);
+    }
+
+    #[TestDox('POST /register uses error code from ClientRegistrationException')]
+    public function testRegistrationUsesCustomErrorCode(): void
+    {
+        $registrar = $this->createMock(ClientRegistrarInterface::class);
+        $registrar->expects($this->once())
+            ->method('register')
+            ->willThrowException(new ClientRegistrationException('Invalid redirect URI', 'invalid_redirect_uri'));
+
+        $middleware = $this->createMiddleware($registrar);
+
+        $request = $this->factory->createServerRequest('POST', 'http://localhost:8000/register')
+            ->withHeader('Content-Type', 'application/json')
+            ->withBody($this->factory->createStream('{}'));
+
+        $response = $middleware->process($request, $this->createPassthroughHandler(404));
+
+        $this->assertSame(400, $response->getStatusCode());
+
+        $payload = json_decode($response->getBody()->__toString(), true, 512, \JSON_THROW_ON_ERROR);
+        $this->assertSame('invalid_redirect_uri', $payload['error']);
+        $this->assertSame('Invalid redirect URI', $payload['error_description']);
+    }
+
     #[TestDox('GET /.well-known/oauth-authorization-server enriches response with registration_endpoint')]
     public function testMetadataEnrichment(): void
     {