Repository navigation
Expand file tree
/
Copy pathRequestStateCodec.php
More file actions
184 lines (149 loc) · 6.28 KB
/
Copy pathRequestStateCodec.php
File metadata and controls
184 lines (149 loc) · 6.28 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
<?php
/*
* This file is part of the official PHP MCP SDK.
*
* A collaboration between Symfony and the PHP Foundation.
*
* For the full copyright and license information, please view the LICENSE
* file that was distributed with this source code.
*/
namespace Mcp\Server\Stateless;
use Mcp\Exception\InvalidArgumentException;
use Mcp\Exception\RequestStateException;
/**
* Seals and verifies the opaque `requestState` carried across the rounds of a
* multi round-trip request (SEP-2322).
*
* The value is `base64url(payload).base64url(HMAC)`. It passes through the
* client, so it is attacker-controlled on return and
* {@see self::verify()} refuses anything whose MAC or expiry does not hold.
* Signed, not encrypted: nothing secret belongs in the payload.
*
* Takes one key or a key ring to rotate without failing the calls in flight:
* the first key signs, every key verifies. The value names no key, so the
* wire format does not change.
*
* A codec {@see self::withBinding() bound} to a value also covers that value
* with the MAC, without putting it on the wire: a state minted under one
* binding fails verification under any other, and so does a state minted
* without one. The wire format is the same either way.
*
* @author Christopher Hertel <mail@christopher-hertel.de>
*/
final class RequestStateCodec
{
/** Below this the MAC — the only thing making the blob trustworthy — is forgeable. */
public const MINIMUM_KEY_BYTES = 32;
private const ALGORITHM = 'sha256';
/** @var non-empty-list<string> */
private readonly array $keys;
/**
* @param string|list<string> $key the signing key, or a key ring whose first key signs and whose every key verifies
*/
public function __construct(
string|array $key,
private readonly int $ttlSeconds = 600,
private readonly ?string $binding = null,
) {
$keys = \is_string($key) ? [$key] : $key;
if ([] === $keys || !array_is_list($keys)) {
throw new InvalidArgumentException('The requestState key ring must be a non-empty list of keys.');
}
foreach ($keys as $i => $candidate) {
$name = \is_string($key) ? 'The requestState signing key' : \sprintf('The requestState signing key at index %d', $i);
if (!\is_string($candidate)) {
throw new InvalidArgumentException(\sprintf('%s must be a string, got %s.', $name, get_debug_type($candidate)));
}
if (\strlen($candidate) < self::MINIMUM_KEY_BYTES) {
throw new InvalidArgumentException(\sprintf('%s must be at least %d bytes, got %d.', $name, self::MINIMUM_KEY_BYTES, \strlen($candidate)));
}
}
$this->keys = $keys;
if ($this->ttlSeconds < 1) {
throw new InvalidArgumentException(\sprintf('The requestState TTL must be at least one second, got %d.', $this->ttlSeconds));
}
}
/**
* A codec with the same keys and TTL whose states only verify under the
* same binding, e.g. the value a {@see RequestStateBinderInterface}
* computed for the request at hand.
*/
public function withBinding(string $binding): self
{
return new self($this->keys, $this->ttlSeconds, $binding);
}
/**
* @param array<string, mixed> $payload server context to carry to the retry — never secrets
*/
public function mint(array $payload, ?int $now = null): string
{
$body = self::encode(json_encode([
'exp' => ($now ?? time()) + $this->ttlSeconds,
'data' => $payload,
], \JSON_THROW_ON_ERROR));
return $body.'.'.self::encode($this->sign($body, $this->keys[0]));
}
/**
* @return array<string, mixed> the payload that was sealed
*
* @throws RequestStateException when the value is malformed, signed by none of the keys,
* bound to something else than this codec, or expired
*/
public function verify(string $state, ?int $now = null): array
{
$parts = explode('.', $state);
if (2 !== \count($parts)) {
throw new RequestStateException('malformed');
}
[$body, $mac] = $parts;
$actual = self::decode($mac);
if (null === $actual) {
throw new RequestStateException('mac');
}
// Every key, no early exit: which key signed is nobody's business. A
// ring holds a handful of keys, so trying each costs next to nothing
// and spares the wire format a key id.
$verified = false;
foreach ($this->keys as $key) {
// Constant-time: a short-circuiting compare is a byte-at-a-time oracle.
$verified = hash_equals($this->sign($body, $key), $actual) || $verified;
}
if (!$verified) {
throw new RequestStateException('mac');
}
$decoded = self::decode($body);
if (null === $decoded) {
throw new RequestStateException('malformed');
}
try {
/** @var array<string, mixed> $claims */
$claims = json_decode($decoded, true, flags: \JSON_THROW_ON_ERROR);
} catch (\JsonException) {
throw new RequestStateException('malformed');
}
if (!\is_array($claims) || !\is_int($claims['exp'] ?? null) || !\is_array($claims['data'] ?? null)) {
throw new RequestStateException('malformed');
}
// Bounds replay; does not make the state single-use.
if ($claims['exp'] < ($now ?? time())) {
throw new RequestStateException('expired');
}
return $claims['data'];
}
private function sign(string $body, string $key): string
{
// The body is base64url, so it never contains the '.' separating it
// from the binding: a bound and an unbound input can never collide.
$input = null === $this->binding ? $body : $body.'.'.$this->binding;
return hash_hmac(self::ALGORITHM, $input, $key, true);
}
private static function encode(string $raw): string
{
return rtrim(strtr(base64_encode($raw), '+/', '-_'), '=');
}
private static function decode(string $encoded): ?string
{
$decoded = base64_decode(strtr($encoded, '-_', '+/'), true);
return false === $decoded ? null : $decoded;
}
}