[Server] Keep issuer and client bound when a resolver names the requestState subject

Author: chr-hertel

CHANGELOG.md

@@ -26,7 +26,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
 * Add `Psr6SessionStore` and `Psr6NotificationBus`, which work like `Psr16SessionStore` and `Psr16NotificationBus` over a PSR-6 cache pool. `Builder::setDiscovery()` also accepts a PSR-6 pool as `$cache`.
 * Fix a nullable tool parameter with a default (e.g. `?string $category = 'books'`) receiving the default when the client explicitly sends `null`: `ReferenceHandler` now passes the `null` through.
 * Fix a `subscriptions/listen` stream that can carry nothing (the server announces none of the requested types, or the client asks for none) being held open for the full subscription lifetime: it is acknowledged with an empty `notifications` filter and closed gracefully right away, instead of pinning a PHP-FPM worker. Adds `NotificationFilter::isEmpty()`.
-* Add a `binder` argument to `Builder::setRequestState()` binding the modern era's `requestState` to the request it was minted for, as the 2026-07-28 specification recommends: the binder's value is covered by the state's MAC, and a state echoed on a request that binds to another value is refused like a forged one. `OriginatingRequestBinder` binds the authenticated principal, the method, the tool, prompt or resource, and a digest of the arguments; a token without a subject fails closed, and a `principal` resolver identifies users by another claim. `RequestStateBinderInterface` takes custom bindings. Without a binder, nothing changes.
+* Add a `binder` argument to `Builder::setRequestState()` binding the modern era's `requestState` to the request it was minted for, as the 2026-07-28 specification recommends: the binder's value is covered by the state's MAC, and a state echoed on a request that binds to another value is refused like a forged one. `OriginatingRequestBinder` binds the authenticated principal, the method, the tool, prompt or resource, and a digest of the arguments; a token without a subject fails closed, and a `subject` resolver identifies users by another claim. `RequestStateBinderInterface` takes custom bindings. Without a binder, nothing changes.
 
 ### Client
 

docs/handlers/input-required.md

@@ -125,13 +125,13 @@ A token without a subject (`sub`) identifies no user, so the binder cannot tell
 one client apart. It fails closed: such a request binds to a value of its own, and a state it
 mints is refused on the retry. If your authorization server identifies users by another claim,
 pass a resolver that returns a value stable across a token refresh, or `null` for a token that
-identifies nobody:
+identifies nobody. The issuer and client stay bound either way:
 
 ```php
 use Mcp\Server\Authorization\AccessToken;
 
 new OriginatingRequestBinder(
-    principal: static fn (AccessToken $token): ?string => \is_string($oid = $token->getClaim('oid')) ? $oid : null,
+    subject: static fn (AccessToken $token): ?string => \is_string($oid = $token->getClaim('oid')) ? $oid : null,
 )
 ```
 

src/Server/Stateless/OriginatingRequestBinder.php

@@ -33,8 +33,9 @@
  *
  * A token without a subject identifies no user: tokens of different users of
  * one client would share a principal. Such a request binds to a value of its
- * own, so the states it mints never verify. Pass a `$principal` resolver when
- * the authorization server identifies users by another claim.
+ * own, so the states it mints never verify. Pass a `$subject` resolver when
+ * the authorization server identifies users by another claim; the issuer
+ * and client stay part of the principal either way.
  *
  * @see https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr#server-requirements-basic-workflow
  *
@@ -46,12 +47,12 @@ final class OriginatingRequestBinder implements RequestStateBinderInterface
     private const ENCODE_DEPTH = 3 * 512;
 
     /**
-     * @param (\Closure(AccessToken): ?string)|null $principal identifies the user and client a token was issued
-     *                                                         for, stable across a token refresh; null when the token
-     *                                                         identifies nobody. Defaults to issuer, client and subject.
+     * @param (\Closure(AccessToken): ?string)|null $subject identifies the user a token was issued for, stable
+     *                                                       across a token refresh; null when the token identifies
+     *                                                       nobody. Defaults to the `sub` claim.
      */
     public function __construct(
-        private readonly ?\Closure $principal = null,
+        private readonly ?\Closure $subject = null,
     ) {
     }
 
@@ -73,34 +74,24 @@ public function bind(Request $request, ?AccessToken $accessToken): string
     }
 
     /**
-     * @return array{identified: string}|array{unidentified: string}
+     * @return array{identified: array{iss: ?string, client: ?string, sub: string}}|array{unidentified: string}
      */
     private function principal(AccessToken $accessToken): array
     {
-        $principal = null === $this->principal ? self::defaultPrincipal($accessToken) : ($this->principal)($accessToken);
-
-        if (null === $principal) {
-            return ['unidentified' => bin2hex(random_bytes(16))];
-        }
-
-        return ['identified' => $principal];
-    }
-
-    private static function defaultPrincipal(AccessToken $accessToken): ?string
-    {
-        $subject = $accessToken->getSubject();
+        $subject = null === $this->subject ? $accessToken->getSubject() : ($this->subject)($accessToken);
 
         if (null === $subject) {
-            return null;
+            return ['unidentified' => bin2hex(random_bytes(16))];
         }
 
         $issuer = $accessToken->getClaim('iss');
 
-        return self::encode([
+        // Not up to the resolver: a state stays with the issuer and client it was minted for.
+        return ['identified' => [
             'iss' => \is_string($issuer) ? $issuer : null,
             'client' => $accessToken->getClientId(),
             'sub' => $subject,
-        ]);
+        ]];
     }
 
     private static function encode(mixed $value): string

tests/Unit/Server/Stateless/OriginatingRequestBinderTest.php

@@ -133,8 +133,8 @@ public function testTokenWithoutSubjectBindsToAValueOfItsOwn(): void
         $this->assertNotSame($binder->bind(self::call(), $token), $binder->bind(self::call(), $token));
     }
 
-    #[TestDox('a principal resolver identifies users by another claim')]
-    public function testPrincipalResolverIdentifiesUsersByAnotherClaim(): void
+    #[TestDox('a subject resolver identifies users by another claim')]
+    public function testSubjectResolverIdentifiesUsersByAnotherClaim(): void
     {
         $binder = new OriginatingRequestBinder(
             static fn (AccessToken $token): ?string => \is_string($oid = $token->getClaim('oid')) ? $oid : null,
@@ -146,8 +146,20 @@ public function testPrincipalResolverIdentifiesUsersByAnotherClaim(): void
         $this->assertNotSame($binder->bind(self::call(), $token('alice', 'a')), $binder->bind(self::call(), null));
     }
 
-    #[TestDox('a principal resolver that identifies nobody fails closed')]
-    public function testPrincipalResolverReturningNullFailsClosed(): void
+    #[TestDox('a subject resolver keeps the issuer and client in the principal')]
+    public function testSubjectResolverKeepsIssuerAndClient(): void
+    {
+        $binder = new OriginatingRequestBinder(
+            static fn (AccessToken $token): ?string => \is_string($oid = $token->getClaim('oid')) ? $oid : null,
+        );
+        $token = static fn (string $issuer, string $clientId): AccessToken => new AccessToken(['read'], ['iss' => $issuer, 'client_id' => $clientId, 'oid' => 'alice']);
+
+        $this->assertNotSame($binder->bind(self::call(), $token('https://auth.example.com', 'app')), $binder->bind(self::call(), $token('https://auth.example.com', 'other-app')));
+        $this->assertNotSame($binder->bind(self::call(), $token('https://auth.example.com', 'app')), $binder->bind(self::call(), $token('https://other.example.com', 'app')));
+    }
+
+    #[TestDox('a subject resolver that identifies nobody fails closed')]
+    public function testSubjectResolverReturningNullFailsClosed(): void
     {
         $binder = new OriginatingRequestBinder(static fn (AccessToken $token): ?string => null);