Operation Allowlists

## The confusion is structural, not careless Ask an engineer how their GraphQL endpoint is protected and "we use persisted queries" is a common answer. It is often the wrong answer, and the reason is worth understanding rather than mocking: the two mechanisms look identical from the outside. Both replace a query document in the request body with a short identifier. Both are described with the same vocabulary — persisted, registered, hashed. Both are conventions rather than specified features. The only place they diverge is what the server does when it does not recognise the identifier, and that is invisible in a hit-path trace, in a client's network tab, and in most architecture diagrams. ## Automatic Persisted Queries: a cache, populated by callers Automatic Persisted Queries is a convention for reducing request size and making a GraphQL request identifiable by a short key. A client hashes its document, sends the hash, and the server tries to look it up. When it misses, the server responds with an error the client is expected to recognise, and the client retries with the hash **and** the full document text. The server verifies that the hash matches the text it was given, stores the pair, and executes. That hash verification is real and it matters, but read what it buys: **integrity, not authority**. It stops one caller from poisoning the entry another caller will hit, because the key is derived from the content. It grants no approval whatsoever — any document whose hash is computed correctly is accepted, stored and executed. An attacker wanting to run a nineteen-level-deep traversal against a hospital appointment graph performs the upload step once, exactly as a legitimate client would, and then runs it by hash forever. The store is also usually not a registry. It is commonly an in-memory or shared cache with eviction, sized for the working set of a client release, because its job is to avoid resending bytes. Entries disappearing is normal and harmless there; entries disappearing from an allowlist is an outage. ## An operation allowlist: a set, populated by the operator An allowlist's set arrives from somewhere the caller does not control — it is deployed alongside, or ahead of, a client release, and it is durable. The server never accepts a document body as a way to grow the set. A request whose identifier is not present gets a refusal, and there is no retry that will make it succeed. That single difference is the whole control: the population channel is authenticated by deployment, and the request path is read-only against the set. Everything else follows from it. Because the set is finite and known before traffic arrives, you can review it, score each document once, count how many documents each client release needs, and enumerate the exact field surface reachable in production. Because the set is durable, removing an entry is a deliberate act with a blast radius you can compute. ## The mode switch that converts one into the other Most implementations of the automatic scheme have a setting that disables registration on miss. Turn it off, pre-populate the store during deployment, and the machinery on the wire is unchanged while the trust model flips. This is the practical route many teams take, and it is legitimate — it also explains the conflation, because the same feature name is attached to both configurations. The interview-worthy formulation: the mechanism is the same, the **policy on a miss** is the security property, and only one of the two configurations has a policy. ## How to interrogate the claim When a team says persisted queries protect their endpoint, ask exactly one question: *what happens when the server sees an identifier it has never seen?* If the answer involves the client sending the document, the endpoint accepts arbitrary documents from anyone willing to take one extra round trip, and every conclusion drawn about bounded cost or a reviewed field surface is unfounded. If the answer is a plain refusal, ask the second question: *who can write to the store, and over what channel?* An allowlist whose registration endpoint is reachable with an ordinary client credential is an allowlist in name only. ## The other reason the distinction matters The two mechanisms fail in opposite directions, which affects how you operate them. An automatic persisted-query cache that loses an entry costs one extra round trip and nobody notices. An allowlist that loses an entry breaks every client holding that document, and a fail-closed gate breaks them completely rather than slowly. If a team migrates from the automatic scheme to enforcement without changing the durability of the store — the same evictable cache, now authoritative — the first eviction is an incident. Recognising that the storage requirements change with the policy is the sign of someone who has actually made the switch rather than read about it.