GraphQL Persisted Queries: payloads y superficie de ataque menores
Cómo las persisted queries reducen los payloads de GraphQL, habilitan el caché en CDN y evitan el abuso de queries arbitrarias.

Cada request de GraphQL envía el documento de la query completo por la red, en cada llamada, para siempre. Un dashboard que dispara la misma query de 40 líneas cien veces en una sesión manda esas mismas 40 líneas cien veces. Peor aún: como el cliente puede enviar cualquier query válida, tu endpoint de GraphQL es efectivamente una consola SQL abierta con pasos extra — a menos que hagas algo al respecto.
Las persisted queries resuelven ambos problemas a la vez. El cliente envía un hash corto en lugar del texto de la query, el servidor resuelve ese hash hacia una operación conocida, y cualquier cosa que no esté en la allowlist se rechaza antes de tocar un resolver. Es uno de esos cambios que se lee como una optimización de rendimiento pero en realidad es un límite de seguridad disfrazado de optimización de rendimiento.
Qué es realmente una Persisted Query
Una persisted query es una operación de GraphQL registrada de antemano e identificada por un hash (típicamente SHA-256 del texto de la query) en lugar del documento crudo. El cliente envía el hash; el servidor busca la query correspondiente en un store que controla.
# ❌ What goes over the wire today, every single request
query GetDashboard($userId: ID!) {
user(id: $userId) {
id
name
recentOrders(limit: 10) {
id
total
status
items {
sku
quantity
}
}
}
}// ✅ What goes over the wire with persisted queries
{
"id": "a13f9e2c8b7d4f0e1a9c8b7d4f0e1a9c",
"variables": { "userId": "usr_8821" }
}El hash es determinista y se deriva del texto de la query, así que dos clientes que registran la misma operación idéntica producen el mismo identificador. Las Automatic Persisted Queries (APQ) de Apollo formalizaron este handshake, y Relay implementa la misma idea como una funcionalidad de primer nivel del compilador en lugar de un fallback en tiempo de ejecución.
Automáticas vs. Totalmente Persistidas
Hay dos variantes, y resuelven problemas distintos.
| Enfoque | Registro | Garantía de seguridad |
|---|---|---|
| Automático (APQ) | Perezoso, en el primer request | Ninguna — cualquier query puede seguir registrándose |
| Totalmente persistido | En build-time, solo allowlist | Fuerte — los hashes desconocidos se rechazan |
APQ es puramente una optimización de ancho de banda: el cliente envía primero un hash y, si el servidor no lo ha visto, el cliente cae de nuevo a enviar la query completa una vez para que el servidor pueda cachearla. Después de eso, cada llamada subsiguiente es solo hash. Es un gran primer paso y requiere casi ningún cambio en el servidor, pero no hace nada para evitar que un atacante registre una query arbitraria propia — el servidor cacheará felizmente lo que sea que se le dé.
Las persisted queries totalmente persistidas cierran ese hueco. La allowlist se construye en tiempo de compilación a partir de tu codebase de cliente real, se envía al servidor como un manifiesto fijo, y el servidor rechaza cualquier cosa que no esté en él. Esta es la versión que vale la pena adoptar si el abuso de introspección o los ataques de complejidad de query están en tu modelo de amenazas, junto con cosas como el análisis de costo de query para limitar profundidad y complejidad.
Construyendo la Allowlist en Build Time
La mayoría de las herramientas de build de GraphQL (el compilador de Relay, graphql-codegen, el paquete persisted-query-lists de Apollo) pueden extraer cada operación del código fuente de tu cliente y generar un manifiesto indexado por hash.
// scripts/build-persisted-queries.ts
import { createHash } from "node:crypto";
import { glob } from "glob";
import { readFile, writeFile } from "node:fs/promises";
import { parse, print } from "graphql";
interface PersistedQueryEntry {
hash: string;
query: string;
operationName: string;
}
async function buildManifest(): Promise<void> {
const files = await glob("src/**/*.graphql");
const entries: PersistedQueryEntry[] = [];
for (const file of files) {
const raw = await readFile(file, "utf8");
// Normalize whitespace so semantically identical
// queries always hash to the same value.
const normalized = print(parse(raw));
const hash = createHash("sha256")
.update(normalized)
.digest("hex");
const operationName =
parse(raw).definitions[0]?.kind === "OperationDefinition"
? (parse(raw).definitions[0] as any).name?.value ?? "anonymous"
: "anonymous";
entries.push({ hash, query: normalized, operationName });
}
await writeFile(
"dist/persisted-queries.json",
JSON.stringify(entries, null, 2),
);
}
buildManifest().catch((err) => {
console.error("Failed to build persisted query manifest:", err);
process.exit(1);
});Ese manifiesto se envía al servidor como parte del deployment — no como una fila de base de datos que un atacante podría envenenar, sino como un artefacto de build atado a una versión específica del cliente.
Aplicando la Allowlist en el Servidor
La verificación del lado del servidor es deliberadamente aburrida: buscar el hash, rechazar si falta, ejecutar la query almacenada con las variables provistas por el cliente.
import type { Request, Response, NextFunction } from "express";
import manifest from "./dist/persisted-queries.json";
const allowlist = new Map(
manifest.map((entry) => [entry.hash, entry.query]),
);
export function persistedQueryGuard(
req: Request,
res: Response,
next: NextFunction,
): void {
const { id, query, variables } = req.body;
// ❌ Never fall back to executing an inline query
// in production once the allowlist is enforced.
if (!id) {
res.status(400).json({ errors: [{ message: "Missing query id" }] });
return;
}
const resolvedQuery = allowlist.get(id);
if (!resolvedQuery) {
res.status(400).json({
errors: [{ message: "Unknown persisted query", code: "PERSISTED_QUERY_NOT_FOUND" }],
});
return;
}
req.body = { query: resolvedQuery, variables };
next();
}El código de error PERSISTED_QUERY_NOT_FOUND replica la convención que los clientes de Apollo ya saben manejar, así que las bibliotecas de cliente existentes degradan con elegancia en lugar de fallar ante una forma desconocida.
Aplicar la allowlist solo vale la pena si la introspección también está desactivada en producción. Una lista de operaciones totalmente bloqueada junto a una query __schema abierta sigue filtrando toda la superficie de tu API a cualquiera que la pida.
Convirtiendo Mutations en Requests GET Cacheables
Como un identificador de persisted query más sus variables determina completamente la respuesta de una query dada, puedes enviar operaciones de lectura como requests GET con el hash y las variables en el query string en lugar de un body POST. Ese solo cambio hace que las respuestas de GraphQL sean cacheables por cualquier caché HTTP estándar — un CDN, un reverse proxy, incluso el navegador — usando la misma semántica de Cache-Control definida en RFC 9111.
# ✅ Cacheable: deterministic URL, standard HTTP caching applies
curl "https://api.example.com/graphql?\
id=a13f9e2c8b7d4f0e1a9c8b7d4f0e1a9c&\
variables=%7B%22userId%22%3A%22usr_8821%22%7D"# ❌ Not cacheable by anything downstream of your app server
curl -X POST https://api.example.com/graphql \
-d '{"query": "query GetDashboard($userId: ID!) { ... }"}'Un CDN ahora puede cachear esa respuesta GET indexada por la URL completa, darte hit rates a nivel de edge para tus queries de lectura más calientes, y recortar latencia real de todo lo que no necesite estar fresco en cada request.
Lanzándolo Sin Romper los Clientes Existentes
Activar la aplicación de la allowlist para todos los clientes a la vez es la forma de tumbar producción. Lánzalo en tres etapas:
- Despliega APQ primero. Sin aplicación de allowlist, solo caché basado en hash. Esto valida la lógica de hashing y fallback con riesgo cero.
- Registra los hashes desconocidos en lugar de rechazarlos. Corre la verificación de allowlist en modo shadow durante un ciclo de release para detectar clientes que olvidaste reconstruir — versiones viejas de la app móvil, en particular.
- Aplica la restricción, con una versión mínima de cliente documentada. Una vez que los logs muestren una tasa de hashes desconocidos en cero para las versiones que planeas soportar, activa el rechazo.
Puntos Clave
- Las persisted queries reemplazan los documentos de query completos con hashes cortos, reduciendo el tamaño del payload en cada request después del primero.
- Las Automatic Persisted Queries son una ganancia de ancho de banda; una allowlist en build-time es la versión que realmente mejora la seguridad.
- Normaliza el texto de la query (vía
print(parse(query))) antes de hashearla para que las queries semánticamente idénticas siempre colapsen a una sola entrada. - Desactiva la introspección junto con la aplicación de la allowlist — una sin la otra deja tu schema descubrible de todos modos.
- Convertir las lecturas persistidas en requests
GEThabilita el caché HTTP y de CDN estándar que GraphQL con soloPOSTnunca obtiene. - Lanza la aplicación primero en modo shadow; un corte duro sobre una allowlist sin registro romperá silenciosamente a cualquier cliente que hayas olvidado.


