graphql-depth-protector

graphql-depth-protector is a drop-in Apollo Server plugin and utility that enforces a configurable maximum query depth for incoming GraphQL operations. It helps protect your GraphQL API from deeply nested queries and recursive fragment attacks that could degrade performance or cause denial of service.

🚀 Features

• 🔐 Enforces a configurable maxDepth
• ⚙️ Supports environment variables and CLI flags
• 🧠 Traverses fragments, inline fragments, and deeply nested fields
• 🧪 Includes standalone depth analysis utilities
• 📊 Optional query depth logging

📦 Installation

npm install graphql-depth-protector

🧩 Usage with Apollo Server

const { ApolloServer } = require('apollo-server');
const { createDepthLimitPlugin } = require('graphql-depth-protector');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    createDepthLimitPlugin({
      maxDepth: 10,
      logDepth: true,
      throwMessage: (depth, max) => `Depth ${depth} > ${max}`,
      onDepthExceeded: (depth, max) => console.warn(`Depth ${depth} exceeded max ${max}`),
      ignoreIntrospection: true,
    })
  ]
});

⚙️ Configuration Options

You can configure the plugin via function options, environment variables, or CLI flags:

| Option | Type | Default | Description | |-----------------------|----------|---------|-------------| | maxDepth | number | 10 | Maximum allowed field depth | | ignoreIntrospection| boolean| true | Skip depth checks for introspection queries | | logDepth | boolean| false | Log detected depth per operation | | throwMessage | function(depth, max) | "Query depth {depth} exceeds max {max}" | Custom error message | | onDepthExceeded | function(depth, max) | null | Hook for custom logging/monitoring |

🌱 Environment Variables

| Env Variable | Effect | |-------------------------------|--------| | GRAPHQL_MAX_DEPTH | Sets maxDepth | | GRAPHQL_IGNORE_INTROSPECTION| false disables introspection skip | | GRAPHQL_LOG_DEPTH | Set to true to enable logging |

🧪 CLI Flags (e.g. node server.js --max-depth 12)

| Flag | Description | |--------------------------|-------------| | --max-depth, -d | Set max depth | | --ignore-introspection | Enable or disable introspection skipping | | --log-depth, -l | Enable depth logging |

🛠 Utilities

validateQueryDepth(queryString, maxDepth)

Check the depth of a raw GraphQL query string.

const { validateQueryDepth } = require('graphql-depth-protector');
const result = validateQueryDepth(queryString, 10);

if (!result.valid) {
  console.error("Too deep!", result);
}

getOperationDepth(documentAST)

Returns the actual depth of a parsed GraphQL document.

const { getOperationDepth } = require('graphql-depth-protector');
const { parse } = require('graphql');
const ast = parse(queryString);
console.log(getOperationDepth(ast));

📄 License

MIT