MCP PHP SDK

RequestStateCodec

FinalYes

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 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 \Mcp\Server\Stateless\self::withBinding() 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.

Tags
author

Christopher Hertel mail@christopher-hertel.de

Table of Contents

Constants

MINIMUM_KEY_BYTES  : mixed = 32
Below this the MAC — the only thing making the blob trustworthy — is forgeable.
ALGORITHM  : mixed = 'sha256'

Properties

$binding  : string|null
$keys  : array<int, string>
$ttlSeconds  : int

Methods

__construct()  : mixed
mint()  : string
verify()  : array<string, mixed>
withBinding()  : self
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.
decode()  : string|null
encode()  : string
sign()  : string

Constants

MINIMUM_KEY_BYTES

Below this the MAC — the only thing making the blob trustworthy — is forgeable.

public mixed MINIMUM_KEY_BYTES = 32

Properties

Methods

__construct()

public __construct(string|array<int, string> $key[, int $ttlSeconds = 600 ][, string|null $binding = null ]) : mixed
Parameters
$key : string|array<int, string>

the signing key, or a key ring whose first key signs and whose every key verifies

$ttlSeconds : int = 600
$binding : string|null = null

mint()

public mint(array<string, mixed> $payload[, int|null $now = null ]) : string
Parameters
$payload : array<string, mixed>

server context to carry to the retry — never secrets

$now : int|null = null
Return values
string

verify()

public verify(string $state[, int|null $now = null ]) : array<string, mixed>
Parameters
$state : string
$now : int|null = null
Tags
throws
RequestStateException

when the value is malformed, signed by none of the keys, bound to something else than this codec, or expired

Return values
array<string, mixed> —

the payload that was sealed

withBinding()

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 withBinding(string $binding) : self
Parameters
$binding : string
Return values
self

decode()

private static decode(string $encoded) : string|null
Parameters
$encoded : string
Return values
string|null

encode()

private static encode(string $raw) : string
Parameters
$raw : string
Return values
string

sign()

private sign(string $body, string $key) : string
Parameters
$body : string
$key : string
Return values
string
On this page

Search results