CSE Roadmap

Common tier · about 6 hours · 14 parts

Part 4 of 14 · 2 min read

requestState is a note the server wrote to itself, carried by someone else

The client that carries the saved state between rounds can read it, and anything that can read it can try to change it.

Think of a coat-check ticket: if the ticket itself could be rewritten by whoever is holding it, anyone could change "coat 14" to "coat 3" and walk off with somebody else's coat.

In plain words: requestState passes through the client between rounds, so the server must treat it as attacker-controlled input. That means sealing it with an HMAC, binding it to the principal and to a digest of the original request, and giving it a short expiry. It also means remembering that a valid, unexpired token can still be replayed more than once unless the server also keeps a record of which ones have already been spent.

A worked example. Against one sealed token: an untouched token is accepted. One changed character, an edited price field with the old signature kept, a token issued to another user, a token applied to a different request, an expired token, and a token signed with the wrong key are all rejected, each with a distinct reason ("bad signature", "issued to a different principal", "belongs to a different request", "expired"). Presented twice within its lifetime with no server-side record, the same valid token is accepted both times. Binding and expiry stop forgery and staleness, but they do not stop replay on their own.

The key lines. From code/mini-input/state.py:

# from code/mini-input/state.py
def open_state(token: str, key: bytes, principal: str | None, method: str, params: dict, now: float | None = None, consumed: set | None = None) -> dict:
    """Verify and return the data. Raises StateError with a reason otherwise. If `consumed` is given, the state can be used once."""
    ...
    if payload["sub"] != principal:
        raise StateError("issued to a different principal")
    if payload["exp"] < now:
        raise StateError("expired")
    if payload["dig"] != request_digest(method, params):
        raise StateError("belongs to a different request")

Read it as: three separate if checks, each raising its own named reason. The function does not collapse "something is wrong" into one generic rejection. It distinguishes a forged principal from an expired token from a mismatched request. Each of those failure reasons tells the server author something different about what to do next. Through the error text, it tells the model too.

requestState

requestState is an opaque value the server writes and the client must echo back unchanged between rounds of a multi round-trip request; because it travels through the client, the server must treat it as attacker-controlled.

Example: the same token accepted twice with no server-side record, and redeemed exactly once once the voucher tool starts tracking its nonce, is the one-time-use gap in a single measurement. Sealing a token answers "was this tampered with," not "has this already been used." Only a server-side record answers the second question.