You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 24360c3
Browse filesBrowse the repository at this point in the historyBrowse files
[Server] Rotate the requestState signing key with a key ring
Builder::setRequestState() and RequestStateCodec take a list of keys:
the first key signs, every key verifies, so an operator can put a new
key in front and drop the old one once the states it signed expired,
without failing the multi round-trip calls in flight.
A state names no key: verification tries each key of the ring, so the
wire format is unchanged and instances of an older release still verify
the states a ring signs. A single key works as before.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,6 +28,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
28
28
* 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()`.
29
29
*[BC Break] Answer `server/discover` with `DiscoverHandler`, which a handler added through `Builder::addRequestHandler()` can replace, and dispatch `RequestEvent`, `ResponseEvent` and `ErrorEvent` for it. A `StatelessProtocol` built without the `Builder` needs `DiscoverHandler` and a `MessageFactory` with `DiscoverRequest` to answer it.
30
30
* 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.
31
+
* Rotate the `requestState` signing key without failing the calls in flight: `Builder::setRequestState()` and `RequestStateCodec` take a list of keys, the first signing and every key verifying. The wire format is unchanged, and a single key works as before.
Copy file name to clipboardExpand all lines: docs/run/server-builder.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -117,6 +117,7 @@ $server = Server::builder()
117
117
// Signs the state a multi round-trip request carries through the client.
118
118
// The same key must reach every process that might serve the retry.
119
119
// The key needs at least 32 bytes, otherwise build() throws. TTL in seconds, default 600.
120
+
// A list of keys rotates them: the first signs, every key verifies.
120
121
// Without a key, the server refuses every state the client sends back.
121
122
// The optional binder ties each state to the principal and the call it was
122
123
// minted for, so a client cannot echo it on another call or under another token.
@@ -336,7 +337,7 @@ $server = Server::builder()
336
337
|`setProtocolVersion()`| protocolVersion | Pin the handshake to one protocol revision |
337
338
|`setModernVersions()`| versions | Narrow the revisions the modern (2026-07-28) leg answers for |
338
339
|`withoutModernEra()`| - | Serve the handshake era only |
339
-
|`setRequestState()`| key, ttl?, binder? | Signing key, lifetime and optional binding to the originating request for multi round-trip request state |
340
+
|`setRequestState()`| key, ttl?, binder? | Signing key (or key ring, the first key signing), lifetime and optional binding to the originating request for multi round-trip request state |
340
341
|`setInputRequiredLimits()`| maxRounds, roundTimeout | Bound the input-required shim on handshake-era connections |
341
342
|`withoutInputRequiredShim()`| - | Do not fulfil an `InputRequiredResult` over a handshake-era connection |
342
343
|`setCachePolicy()`| policy | Set the `ttlMs`/`cacheScope` hints on cacheable results |
Copy file name to clipboardExpand all lines: src/Server/Stateless/RequestStateCodec.php
+51-13Lines changed: 51 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -23,6 +23,10 @@
23
23
* {@see self::verify()} refuses anything whose MAC or expiry does not hold.
24
24
* Signed, not encrypted: nothing secret belongs in the payload.
25
25
*
26
+
* Takes one key or a key ring to rotate without failing the calls in flight:
27
+
* the first key signs, every key verifies. The value names no key, so the
28
+
* wire format does not change.
29
+
*
26
30
* A codec {@see self::withBinding() bound} to a value also covers that value
27
31
* with the MAC, without putting it on the wire: a state minted under one
28
32
* binding fails verification under any other, and so does a state minted
@@ -37,28 +41,50 @@ final class RequestStateCodec
37
41
38
42
privateconstALGORITHM = 'sha256';
39
43
44
+
/** @var non-empty-list<string> */
45
+
privatereadonlyarray$keys;
46
+
47
+
/**
48
+
* @param string|list<string> $key the signing key, or a key ring whose first key signs and whose every key verifies
49
+
*/
40
50
publicfunction__construct(
41
-
privatereadonlystring$key,
51
+
string|array$key,
42
52
privatereadonlyint$ttlSeconds = 600,
43
53
privatereadonly ?string$binding = null,
44
54
) {
45
-
if (\strlen($this->key) < self::MINIMUM_KEY_BYTES) {
46
-
thrownewInvalidArgumentException(\sprintf('The requestState signing key must be at least %d bytes, got %d.', self::MINIMUM_KEY_BYTES, \strlen($this->key)));
55
+
$keys = \is_string($key) ? [$key] : $key;
56
+
57
+
if ([] === $keys || !array_is_list($keys)) {
58
+
thrownewInvalidArgumentException('The requestState key ring must be a non-empty list of keys.');
59
+
}
60
+
61
+
foreach ($keysas$i => $candidate) {
62
+
$name = \is_string($key) ? 'The requestState signing key' : \sprintf('The requestState signing key at index %d', $i);
63
+
64
+
if (!\is_string($candidate)) {
65
+
thrownewInvalidArgumentException(\sprintf('%s must be a string, got %s.', $name, get_debug_type($candidate)));
66
+
}
67
+
68
+
if (\strlen($candidate) < self::MINIMUM_KEY_BYTES) {
69
+
thrownewInvalidArgumentException(\sprintf('%s must be at least %d bytes, got %d.', $name, self::MINIMUM_KEY_BYTES, \strlen($candidate)));
70
+
}
47
71
}
48
72
73
+
$this->keys = $keys;
74
+
49
75
if ($this->ttlSeconds < 1) {
50
76
thrownewInvalidArgumentException(\sprintf('The requestState TTL must be at least one second, got %d.', $this->ttlSeconds));
51
77
}
52
78
}
53
79
54
80
/**
55
-
* A codec with the same key and TTL whose states only verify under the
81
+
* A codec with the same keys and TTL whose states only verify under the
56
82
* same binding, e.g. the value a {@see RequestStateBinderInterface}
0 commit comments