o1-labs / o1-labs/Archive-Node-API

Enforce documented GraphQL armor depth floor

Open
#218 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

P2 production-readiness
Dominant language
TypeScript
Stars
19
Forks
9
Avg merge
14h 20m
Merged PRs (30d)
8

Description

Context

#183 documents that GRAPHQL_MAX_DEPTH must not be set below 8, because known downstream clients send depth-7 queries and a depth rejection replaces the validation error text they use for schema-tier fallback.

The default is now safe (12), but the documented floor is not enforced: the parser accepts any integer >= 1, so GRAPHQL_MAX_DEPTH=6 is silently honored.

Follow-up work

  • Decide whether the floor should be enforced or only warned. The safer behavior is to warn loudly or clamp/reject values below the known-safe floor.
  • Add an explicit unit test that the default depth remains above the downstream floor, instead of relying indirectly on the real-query armor test.
  • Add a code comment near maxCost: 5000 explaining that the current safety margin depends on this schema using limit: rather than first: / last:. If future schema work adds first or last pagination arguments, the cost budget must be revisited.
  • Mention the transitive graphql version bump in the PR/release notes because downstream consumers treat graphql-js validation error text as a contract.

Acceptance criteria

  • GRAPHQL_MAX_DEPTH < 8 produces a warning, clamp, or startup validation error with a clear message.
  • Unit coverage explicitly pins the default depth above the documented downstream floor.
  • Cost-limit comments or docs flag the first / last pagination multiplier hazard.
  • Release notes call out the graphql-js version involved in the armor dependency tree.

Related

  • #183
  • #198

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the parser handling GRAPHQL_MAX_DEPTH and the existing real-query armor test. Decide and document the below-8 behavior, then add explicit coverage that the default remains above the downstream floor. Also inspect the maxCost: 5000 comment and release-note process so the pagination hazard and transitive graphql-js version are recorded.

Written by the indexing model from the issue text.

Assessment

Tech stack
graphql, typescript
Domain
api, release, security, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.