Use EXPLAIN-based validation as primary Cypher query security boundary

[JeroenDeDauw]

Below description comes from C Opus 45 based on my prompt and is approved.

Problem

CypherQueryFilter uses a keyword blocklist to reject non-read queries. This is inherently fragile:
new Neo4j versions can introduce new write/admin keywords, and it's easy to miss one. Issues #479 and
#480 are symptoms of this — we keep discovering keywords we forgot to block.

Proposed approach

Use Neo4j's own query planning as the primary security boundary. Before executing a user-provided
Cypher query, run EXPLAIN <query> against Neo4j. The Bolt protocol result summary includes a
queryType field (r, w, rw, s). If it's not r, reject.

This delegates parsing to the one authority that definitively knows what constitutes a write — Neo4j
itself. No keyword list to maintain, and it's future-proof against new syntax.

Tradeoffs

• One extra round-trip per user query (EXPLAIN then execute). Acceptable for #cypher_raw since a
  Neo4j call is already being made.
• Need to verify the Laudis PHP client exposes queryType from the result summary.
• EXPLAIN itself should be safe (read-only by design), but worth verifying.

Role of existing CypherQueryFilter

Keep the keyword filter as a fast-fail / defense-in-depth layer. It rejects obviously bad queries
without hitting Neo4j. But it no longer needs to be the sole security boundary, so missing a keyword
becomes "slightly wasteful round-trip" rather than "security hole."

SHOW as a special case

SHOW queries (e.g. SHOW USERS, SHOW DATABASES) are read-only from Neo4j's perspective, so
EXPLAIN would classify them as r. If blocking information disclosure is desired, the keyword filter
is still needed for that — it's a policy decision beyond read-vs-write.

AC

• User-provided Cypher queries are validated via EXPLAIN before execution
• Non-read queries are rejected based on the EXPLAIN result
• CypherQueryFilter keyword blocklist is retained as secondary defense
• Tests

References

• ADR 013: Restrict Neo4j Access
• Neo4j Reserved Words

[JeroenDeDauw]

Claude code posted comment based on input from Jeroen:

Performance impact analysis of EXPLAIN-based validation

Overall: minor impact for typical usage, acceptable tradeoff for the security improvement

The extra EXPLAIN round-trip adds ~3–10ms per #cypher_raw query. For a typical query taking 50ms to execute, that's roughly a 10% increase in total time. For fast queries (~5ms), the relative overhead is higher but the absolute cost remains small.

Key considerations:

• No per-request result caching exists — every page render re-executes all #cypher_raw calls, so EXPLAIN runs every time too. Pages with multiple queries multiply the overhead linearly.
• The keyword filter as fast-fail mitigates this — obviously bad queries never reach Neo4j, so EXPLAIN only runs for queries that pass the keyword check.
• MediaWiki page caching means rendered pages aren't regenerated on every view, only on edit/purge, which limits how often the overhead is felt in practice.

If the linear stacking on pages with many queries becomes a problem, a natural mitigation would be caching the EXPLAIN result per query string within a request. Not necessary upfront though.