graphql-query-depth-limit-esm 2.0.1 → 2.0.4

package/README.md

@@ -11,7 +11,19 @@
 
 Production-ready GraphQL query depth limiting as a validation rule. Prevents denial-of-service attacks from deeply nested queries by enforcing a configurable maximum depth.
 
-Explore the library's internal function architecture with the **[interactive node-based visualization](https://lafittemehdy.github.io/graphql-query-depth-limit-esm/architecture.html)**.
+**[Interactive demo](https://lafittemehdy.github.io/graphql-query-depth-limit-esm/)** — see depth analysis in action with preset queries, an AST tree viewer, and a depth gauge.
+
+## Interactive Demo
+
+**[Try it live](https://lafittemehdy.github.io/graphql-query-depth-limit-esm/)** or run locally:
+
+```bash
+cd examples/visualization
+npm install
+npm run dev
+```
+
+Includes preset queries (simple lookups through deeply nested attacks), an AST tree viewer with depth badges, and a depth gauge with pass/fail verdict.
 
 ## Features
 
@@ -29,18 +41,18 @@ Explore the library's internal function architecture with the **[interactive nod
 ## Installation
 
 ```bash
-pnpm add graphql-query-depth-limit-esm graphql
+npm install graphql-query-depth-limit-esm graphql
 ```
 
 ```bash
-npm install graphql-query-depth-limit-esm graphql
+pnpm add graphql-query-depth-limit-esm graphql
 ```
 
 ```bash
 yarn add graphql-query-depth-limit-esm graphql
 ```
 
-## Quick Start
+## Quickstart
 
 ```ts
 import { specifiedRules, validate } from "graphql";
@@ -302,7 +314,7 @@ Monitor query depths with an optional [`callback`](#depthcallback) that receives
 
 ```ts
 const rule = depthLimit(10, {}, (depths) => {
-  // { "GetUser": 3, "ListPosts": 5, "anonymous": 2 }
+  // { "GetUser": 3, "ListPosts": 5, "[anonymous]": 2 }
   for (const [operation, depth] of Object.entries(depths)) {
     console.log(`Operation "${operation}" has depth ${depth}`);
   }
@@ -482,6 +494,21 @@ query {
 # Maximum depth: 3
 ```
 
+## Performance
+
+The depth engine uses **iterative DFS** (not recursion) to prevent stack overflow on adversarial queries and to keep traversal overhead constant regardless of nesting depth.
+
+| Characteristic | Detail |
+|---|---|
+| **Algorithm** | Iterative depth-first search with explicit stack |
+| **Time complexity** | O(n) where n = total selection nodes in the query |
+| **Short-circuit** | Stops on first violation when no callback is provided |
+| **Fragment cycles** | Detected per-path with minimal Set allocations |
+| **Stack safety** | No recursion — immune to stack overflow on deep queries |
+| **Runtime dependencies** | Zero — only `graphql` as a peer dependency |
+
+Typical validation completes in **sub-millisecond** time for standard queries (< 50 fields). Even adversarial queries with hundreds of nested selections are analyzed in **single-digit milliseconds** thanks to early termination and per-path fragment cycle detection.
+
 ## Migrating from v1 to v2
 
 v2 introduces three **breaking changes** with more secure defaults:
@@ -518,6 +545,17 @@ depthLimit(10, { directiveMode: "override", useDirective: true });
 
 **Impact:** This is transparent to most users. The only observable difference is that error messages may report the depth at the first violation rather than the deepest violation when multiple branches exceed the limit. If you need the true maximum depth, provide a callback.
 
+## Related Packages
+
+This package is part of a suite of GraphQL security tools that work independently or together to protect your API:
+
+| Package | Purpose |
+|---|---|
+| [`graphql-query-complexity-esm`](https://github.com/lafittemehdy/graphql-query-complexity-esm) | Complexity analysis — assign cost scores to fields and reject expensive queries |
+| [`graphql-rate-limit-redis-esm`](https://github.com/lafittemehdy/graphql-rate-limit-redis-esm) | Rate limiting — Redis-backed per-field rate limiting via `@rateLimit` directive |
+
+**Recommended layering:** Use depth limiting as a fast, cheap first gate, complexity analysis for fine-grained cost control, and rate limiting for per-client throttling.
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.cjs

@@ -22,7 +22,8 @@ var index_exports = {};
 __export(index_exports, {
   ERROR_CODES: () => ERROR_CODES,
   depthDirectiveTypeDefs: () => depthDirectiveTypeDefs,
-  depthLimit: () => depthLimit
+  depthLimit: () => depthLimit,
+  isUnsafeRegExp: () => isUnsafeRegExp
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -40,9 +41,10 @@ var import_graphql2 = require("graphql");
 
 // src/directives.ts
 var import_graphql = require("graphql");
-var depthDirectiveTypeDefs = `
-  directive @depth(max: Int!) on FIELD_DEFINITION
-`;
+var depthDirectiveTypeDefs = (
+  /* GraphQL */
+  `directive @depth(max: Int!) on FIELD_DEFINITION`
+);
 function getDepthFromDirective(field) {
   if (!field?.astNode?.directives) {
     return void 0;
@@ -62,6 +64,83 @@ function getDepthFromDirective(field) {
 }
 
 // src/ignore.ts
+var QUANTIFIER_CHARS = /* @__PURE__ */ new Set(["+", "*", "?"]);
+var BRACE_QUANTIFIER = /^\{(\d+)(?:,(\d*))?\}/;
+function isUnsafeRegExp(regex) {
+  const source = regex.source;
+  const length = source.length;
+  const groupStack = [];
+  for (let i = 0; i < length; i++) {
+    const char = source.charAt(i);
+    if (char === "\\") {
+      i++;
+      continue;
+    }
+    if (char === "[") {
+      while (i < length && source[i] !== "]") {
+        if (source[i] === "\\") i++;
+        i++;
+      }
+      continue;
+    }
+    if (char === "(") {
+      groupStack.push(false);
+      if (source[i + 1] === "?") {
+        i++;
+        if (source[i + 1] === "<" && (source[i + 2] === "=" || source[i + 2] === "!")) {
+          i += 2;
+        } else if (source[i + 1] === ":" || source[i + 1] === "=" || source[i + 1] === "!") {
+          i++;
+        }
+      }
+      continue;
+    }
+    if (char === ")") {
+      const groupHadQuantifier = groupStack.pop() ?? false;
+      if (groupHadQuantifier && isFollowedByQuantifier(source, i + 1, length)) {
+        return "nested quantifier: group with inner quantifier followed by outer quantifier";
+      }
+      if (groupStack.length > 0 && isFollowedByQuantifier(source, i + 1, length)) {
+        groupStack[groupStack.length - 1] = true;
+      }
+      continue;
+    }
+    if (QUANTIFIER_CHARS.has(char) || char === "{") {
+      if (char === "{") {
+        const match = BRACE_QUANTIFIER.exec(source.slice(i));
+        if (!match) continue;
+        const minStr = match[1] ?? "0";
+        const min = Number.parseInt(minStr, 10);
+        const fullMatch = match[0] ?? "";
+        const hasComma = fullMatch.includes(",");
+        if (!hasComma && min <= 1) continue;
+        if (hasComma && match[2] !== void 0 && match[2] !== "" && Number.parseInt(match[2], 10) <= 1)
+          continue;
+      }
+      if (groupStack.length > 0) {
+        groupStack[groupStack.length - 1] = true;
+      }
+    }
+  }
+  return null;
+}
+function isFollowedByQuantifier(source, pos, length) {
+  if (pos >= length) return false;
+  const char = source[pos];
+  if (char === "+" || char === "*") return true;
+  if (char === "{") {
+    const match = BRACE_QUANTIFIER.exec(source.slice(pos));
+    if (match) {
+      const minStr = match[1] ?? "0";
+      const min = Number.parseInt(minStr, 10);
+      const fullMatch = match[0] ?? "";
+      const hasComma = fullMatch.includes(",");
+      if (!hasComma && min <= 1) return false;
+      return true;
+    }
+  }
+  return false;
+}
 function shouldIgnoreField(fieldName, ignore, caseInsensitive = false, introspectionMode = "typename") {
   if (introspectionMode === "all" && fieldName.startsWith("__")) {
     return true;
@@ -132,8 +211,11 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
     if (!frame.node.selectionSet) {
       continue;
     }
-    const nextFrames = [];
-    for (const selection of frame.node.selectionSet.selections) {
+    for (let selectionIndex = frame.node.selectionSet.selections.length - 1; selectionIndex >= 0; selectionIndex--) {
+      const selection = frame.node.selectionSet.selections[selectionIndex];
+      if (!selection) {
+        continue;
+      }
       switch (selection.kind) {
         case import_graphql2.Kind.FIELD: {
           const fieldName = selection.name.value;
@@ -214,7 +296,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
               deepestViolation = violation;
             }
           }
-          nextFrames.push({
+          stack.push({
             currentDepth: newDepth,
             hasDirectiveLimit,
             ignoredFieldsOnPath,
@@ -238,7 +320,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
           const fragmentVisited = new Set(frame.visitedFragments);
           fragmentVisited.add(fragmentName);
           const parentType2 = fragment.typeCondition ? resolveTypeCondition(fragment.typeCondition.name.value, schema, frame.parentType) : frame.parentType;
-          nextFrames.push({
+          stack.push({
             currentDepth: frame.currentDepth,
             hasDirectiveLimit: frame.hasDirectiveLimit,
             ignoredFieldsOnPath: frame.ignoredFieldsOnPath,
@@ -252,7 +334,7 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
         }
         case import_graphql2.Kind.INLINE_FRAGMENT: {
           const parentType2 = selection.typeCondition ? resolveTypeCondition(selection.typeCondition.name.value, schema, frame.parentType) : frame.parentType;
-          nextFrames.push({
+          stack.push({
             currentDepth: frame.currentDepth,
             hasDirectiveLimit: frame.hasDirectiveLimit,
             ignoredFieldsOnPath: frame.ignoredFieldsOnPath,
@@ -270,12 +352,6 @@ function calculateDepth(caches, config, fragments, maxDepth, node, parentType, s
         }
       }
     }
-    for (let index = nextFrames.length - 1; index >= 0; index--) {
-      const nextFrame = nextFrames[index];
-      if (nextFrame) {
-        stack.push(nextFrame);
-      }
-    }
   }
   return { depth: globalMaxDepth, violation: deepestViolation };
 }
@@ -376,10 +452,129 @@ function resolveTypeCondition(typeConditionName, schema, currentParentType) {
   return currentParentType;
 }
 
-// src/depth-limit.ts
+// src/depth-options.ts
 var DIRECTIVE_MODES = /* @__PURE__ */ new Set(["cap", "override"]);
 var IGNORE_MODES = /* @__PURE__ */ new Set(["exclude", "skip"]);
 var INTROSPECTION_MODES = /* @__PURE__ */ new Set(["all", "none", "typename"]);
+function assertBooleanOption(name, value) {
+  if (value !== void 0 && typeof value !== "boolean") {
+    throw new TypeError(`Invalid ${name}: expected boolean, received ${typeof value}.`);
+  }
+}
+function isIgnoreRule(rule) {
+  return typeof rule === "function" || rule instanceof RegExp || typeof rule === "string";
+}
+function normalizeIgnoreRules(ignore) {
+  if (ignore == null) {
+    return void 0;
+  }
+  const rules = Array.isArray(ignore) ? ignore : [ignore];
+  for (const [index, rule] of rules.entries()) {
+    if (!isIgnoreRule(rule)) {
+      const receivedType = Array.isArray(rule) ? "array" : rule === null ? "null" : typeof rule;
+      throw new TypeError(
+        `Invalid ignore rule at index ${index}: expected string, RegExp, or function, received ${receivedType}.`
+      );
+    }
+    if (rule instanceof RegExp) {
+      const reason = isUnsafeRegExp(rule);
+      if (reason) {
+        throw new TypeError(
+          `Unsafe RegExp ignore rule at index ${index}: /${rule.source}/${rule.flags} - ${reason}. Use a simpler pattern to avoid catastrophic backtracking.`
+        );
+      }
+    }
+  }
+  return rules;
+}
+function normalizeDepthLimitOptions(options) {
+  assertBooleanOption("caseInsensitiveIgnore", options.caseInsensitiveIgnore);
+  if (options.directiveMode !== void 0 && !DIRECTIVE_MODES.has(options.directiveMode)) {
+    throw new TypeError(
+      `Invalid directiveMode: "${options.directiveMode}". Must be "cap" or "override".`
+    );
+  }
+  if (options.ignoreIntrospection !== void 0 && !INTROSPECTION_MODES.has(options.ignoreIntrospection)) {
+    throw new TypeError(
+      `Invalid ignoreIntrospection: "${options.ignoreIntrospection}". Must be "all", "none", or "typename".`
+    );
+  }
+  if (options.ignoreMode !== void 0 && !IGNORE_MODES.has(options.ignoreMode)) {
+    throw new TypeError(
+      `Invalid ignoreMode: "${options.ignoreMode}". Must be "exclude" or "skip".`
+    );
+  }
+  assertBooleanOption("limitIgnoredRecursion", options.limitIgnoredRecursion);
+  assertBooleanOption("shortCircuit", options.shortCircuit);
+  assertBooleanOption("useDirective", options.useDirective);
+  const ignore = normalizeIgnoreRules(options.ignore);
+  return { ...options, ignore };
+}
+function normalizeDepthLimitArgs(options, callback) {
+  if (callback !== void 0 && typeof callback !== "function") {
+    throw new TypeError("Invalid callback: expected a function.");
+  }
+  if (typeof options === "function") {
+    if (callback) {
+      throw new TypeError("Invalid depthLimit arguments: callback provided twice.");
+    }
+    return { callback: options, options: void 0 };
+  }
+  if (options !== void 0 && (options === null || typeof options !== "object" || Array.isArray(options))) {
+    const receivedType = Array.isArray(options) ? "array" : options === null ? "null" : typeof options;
+    throw new TypeError(`Invalid options: expected an object, received ${receivedType}.`);
+  }
+  return {
+    callback,
+    options: options ? normalizeDepthLimitOptions(options) : void 0
+  };
+}
+function createDepthResultRecord() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function createOperationNameAllocator(operations) {
+  const explicitNames = /* @__PURE__ */ new Set();
+  for (const operation of operations) {
+    if (operation.name?.value) {
+      explicitNames.add(operation.name.value);
+    }
+  }
+  const usedNames = /* @__PURE__ */ new Set();
+  const namedCounts = /* @__PURE__ */ new Map();
+  let anonymousCount = 0;
+  return (operation) => {
+    const explicitName = operation.name?.value;
+    if (explicitName) {
+      let suffix = namedCounts.get(explicitName) ?? 0;
+      let candidate2 = suffix === 0 ? explicitName : `${explicitName}_${suffix}`;
+      while (usedNames.has(candidate2) || suffix > 0 && explicitNames.has(candidate2)) {
+        suffix++;
+        candidate2 = `${explicitName}_${suffix}`;
+      }
+      namedCounts.set(explicitName, suffix + 1);
+      usedNames.add(candidate2);
+      return candidate2;
+    }
+    anonymousCount++;
+    let candidate = anonymousCount === 1 ? "[anonymous]" : `[anonymous:${anonymousCount}]`;
+    while (usedNames.has(candidate) || explicitNames.has(candidate)) {
+      anonymousCount++;
+      candidate = `[anonymous:${anonymousCount}]`;
+    }
+    usedNames.add(candidate);
+    return candidate;
+  };
+}
+function setDepthResult(target, key, value) {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true
+  });
+}
+
+// src/depth-limit.ts
 function depthLimit(maxDepth, options, callback) {
   if (!Number.isInteger(maxDepth) || maxDepth < 0) {
     throw new Error(`Invalid maxDepth: ${maxDepth}. Must be a non-negative integer.`);
@@ -387,11 +582,6 @@ function depthLimit(maxDepth, options, callback) {
   const normalized = normalizeDepthLimitArgs(options, callback);
   return createValidationRule(maxDepth, normalized.options, normalized.callback);
 }
-function assertBooleanOption(name, value) {
-  if (value !== void 0 && typeof value !== "boolean") {
-    throw new TypeError(`Invalid ${name}: expected boolean, received ${typeof value}.`);
-  }
-}
 function createValidationRule(maxDepth, options, callback) {
   const shortCircuit = options?.shortCircuit ?? callback == null;
   return function depthLimitValidationRule(context) {
@@ -473,115 +663,11 @@ function createValidationRule(maxDepth, options, callback) {
     return {};
   };
 }
-function isIgnoreRule(rule) {
-  return typeof rule === "function" || rule instanceof RegExp || typeof rule === "string";
-}
-function normalizeDepthLimitArgs(options, callback) {
-  if (callback !== void 0 && typeof callback !== "function") {
-    throw new TypeError("Invalid callback: expected a function.");
-  }
-  if (typeof options === "function") {
-    if (callback) {
-      throw new TypeError("Invalid depthLimit arguments: callback provided twice.");
-    }
-    return { callback: options, options: void 0 };
-  }
-  if (options !== void 0 && (options === null || typeof options !== "object" || Array.isArray(options))) {
-    const receivedType = Array.isArray(options) ? "array" : options === null ? "null" : typeof options;
-    throw new TypeError(`Invalid options: expected an object, received ${receivedType}.`);
-  }
-  return {
-    callback,
-    options: options ? normalizeDepthLimitOptions(options) : void 0
-  };
-}
-function normalizeDepthLimitOptions(options) {
-  assertBooleanOption("caseInsensitiveIgnore", options.caseInsensitiveIgnore);
-  if (options.directiveMode !== void 0 && !DIRECTIVE_MODES.has(options.directiveMode)) {
-    throw new TypeError(
-      `Invalid directiveMode: "${options.directiveMode}". Must be "cap" or "override".`
-    );
-  }
-  if (options.ignoreIntrospection !== void 0 && !INTROSPECTION_MODES.has(options.ignoreIntrospection)) {
-    throw new TypeError(
-      `Invalid ignoreIntrospection: "${options.ignoreIntrospection}". Must be "all", "none", or "typename".`
-    );
-  }
-  if (options.ignoreMode !== void 0 && !IGNORE_MODES.has(options.ignoreMode)) {
-    throw new TypeError(
-      `Invalid ignoreMode: "${options.ignoreMode}". Must be "exclude" or "skip".`
-    );
-  }
-  assertBooleanOption("limitIgnoredRecursion", options.limitIgnoredRecursion);
-  assertBooleanOption("shortCircuit", options.shortCircuit);
-  assertBooleanOption("useDirective", options.useDirective);
-  const ignore = normalizeIgnoreRules(options.ignore);
-  return { ...options, ignore };
-}
-function normalizeIgnoreRules(ignore) {
-  if (ignore == null) {
-    return void 0;
-  }
-  const rules = Array.isArray(ignore) ? ignore : [ignore];
-  for (const [index, rule] of rules.entries()) {
-    if (!isIgnoreRule(rule)) {
-      const receivedType = Array.isArray(rule) ? "array" : rule === null ? "null" : typeof rule;
-      throw new TypeError(
-        `Invalid ignore rule at index ${index}: expected string, RegExp, or function, received ${receivedType}.`
-      );
-    }
-  }
-  return rules;
-}
-function createDepthResultRecord() {
-  return /* @__PURE__ */ Object.create(null);
-}
-function createOperationNameAllocator(operations) {
-  const explicitNames = /* @__PURE__ */ new Set();
-  for (const operation of operations) {
-    if (operation.name?.value) {
-      explicitNames.add(operation.name.value);
-    }
-  }
-  const usedNames = /* @__PURE__ */ new Set();
-  const namedCounts = /* @__PURE__ */ new Map();
-  let anonymousCount = 0;
-  return (operation) => {
-    const explicitName = operation.name?.value;
-    if (explicitName) {
-      let suffix2 = namedCounts.get(explicitName) ?? 0;
-      let candidate2 = suffix2 === 0 ? explicitName : `${explicitName}_${suffix2}`;
-      while (usedNames.has(candidate2) || suffix2 > 0 && explicitNames.has(candidate2)) {
-        suffix2++;
-        candidate2 = `${explicitName}_${suffix2}`;
-      }
-      namedCounts.set(explicitName, suffix2 + 1);
-      usedNames.add(candidate2);
-      return candidate2;
-    }
-    let suffix = anonymousCount;
-    let candidate = suffix === 0 ? "anonymous" : `anonymous_${suffix}`;
-    while (usedNames.has(candidate) || explicitNames.has(candidate)) {
-      suffix++;
-      candidate = `anonymous_${suffix}`;
-    }
-    anonymousCount = suffix + 1;
-    usedNames.add(candidate);
-    return candidate;
-  };
-}
-function setDepthResult(target, key, value) {
-  Object.defineProperty(target, key, {
-    configurable: true,
-    enumerable: true,
-    value,
-    writable: true
-  });
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ERROR_CODES,
   depthDirectiveTypeDefs,
-  depthLimit
+  depthLimit,
+  isUnsafeRegExp
 });
 //# sourceMappingURL=index.cjs.map