graphql-safe-guards 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [1.1.0] – 2026-01-22
+
+### Added
+
+- `ignoreIntrospection` option to allow GraphQL introspection queries
+  without applying depth and complexity validation.
+- Documentation explaining how to use `ignoreIntrospection` with
+  GraphQL Playground and Apollo Sandbox.
+- Security guidelines for private APIs with introspection enabled.
+
+### Changed
+
+- Improved README clarity around introspection and validation behavior.
+
+### Fixed
+
+- Prevented GraphQL introspection queries from being blocked by strict
+  depth or complexity limits when `ignoreIntrospection` is enabled.
+
+---
+
+## [1.0.2]
+
+### Added
+
+- Preset-based configuration (`strict`, `balanced`, `relaxed`)
+- Integration tests validating combined depth and complexity limits
+
+### Fixed
+
+- Type-safe preset resolution

package/README.md

@@ -1,9 +1,15 @@
+![CI](https://github.com/Mateodiaz401/graphql-safe-guards/actions/workflows/ci.yml/badge.svg)
+![npm](https://img.shields.io/npm/v/graphql-safe-guards)
+![downloads](https://img.shields.io/npm/dm/graphql-safe-guards)
+![license](https://img.shields.io/npm/l/graphql-safe-guards)
+![typescript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
 # graphql-safe-guards
 
 Protect your GraphQL API with a single import.
 
 A tiny utility that **combines depth limiting and query complexity validation**
-using native GraphQL validation rules.
+using **native GraphQL validation rules**.
 
 ---
 
@@ -38,6 +44,33 @@ const server = new ApolloServer({
 createSafeGuards({
   depth?: number;       // default: 5
   complexity?: number;  // default: 100
+
+  /**
+   * If true, GraphQL introspection queries are ignored
+   * by depth and complexity validation.
+   *
+   * Useful for GraphQL Playground / Apollo Sandbox.
+   */
+  ignoreIntrospection?: boolean; // default: false
+});
+```
+
+Security Note ⚠️
+
+- This library does not enable or disable GraphQL introspection
+
+- Introspection is controlled by your GraphQL server (e.g. Apollo Server)
+  For private APIs with documentation enabled, the recommended setup is:
+
+```ts
+const server = new ApolloServer({
+  schema,
+  introspection: true,
+  validationRules: createSafeGuards({
+    depth: 3,
+    complexity: 10,
+    ignoreIntrospection: true,
+  }),
 });
 ```
 
@@ -57,6 +90,8 @@ Internally, this package composes:
 - `graphql-safe-depth`
 - `graphql-complexity-validation`
 
+The combination is validated through integration tests using native GraphQL validation.
+
 ---
 
 ## Supported Frameworks
@@ -79,6 +114,18 @@ for GraphQL query safety.
 
 ---
 
+## 🗺️ Roadmap
+
+### v1.x (current)
+
+- ✅ Combine depth + complexity validation
+- ✅ Presets support (`strict`, `balanced`, `relaxed`)
+- ✅ Backward-compatible API
+- ✅ Integration tests with `graphql-js`
+- 🔜 Preset for private APIs (privateApi)
+
+> Roadmap items may change based on feedback and real-world usage.
+
 ## License
 
 MIT © Mateo Diaz

package/dist/index.js

@@ -4,15 +4,26 @@ exports.createSafeGuards = createSafeGuards;
 const graphql_safe_depth_1 = require("graphql-safe-depth");
 const graphql_complexity_validation_1 = require("graphql-complexity-validation");
 const presets_1 = require("./presets");
+const wrapIgnoreIntrospection_1 = require("./utils/wrapIgnoreIntrospection");
 function createSafeGuards(options = {}) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     const presetConfig = options.preset
         ? presets_1.SAFE_GUARD_PRESETS[options.preset]
         : undefined;
     const depth = (_b = (_a = options.depth) !== null && _a !== void 0 ? _a : presetConfig === null || presetConfig === void 0 ? void 0 : presetConfig.depth) !== null && _b !== void 0 ? _b : 5;
     const complexity = (_d = (_c = options.complexity) !== null && _c !== void 0 ? _c : presetConfig === null || presetConfig === void 0 ? void 0 : presetConfig.complexity) !== null && _d !== void 0 ? _d : 100;
-    return [
+    const ignoreIntrospection = (_e = options.ignoreIntrospection) !== null && _e !== void 0 ? _e : false;
+    const rules = [
         (0, graphql_safe_depth_1.createDepthLimitRule)({ maxDepth: depth }),
         (0, graphql_complexity_validation_1.createComplexityLimitRule)({ maxComplexity: complexity }),
     ];
+    if (!ignoreIntrospection) {
+        return rules;
+    }
+    return rules.map((rule) => (0, wrapIgnoreIntrospection_1.wrapIgnoreIntrospection)(rule));
+    // el original
+    // return [
+    //   createDepthLimitRule({ maxDepth: depth }),
+    //   createComplexityLimitRule({ maxComplexity: complexity }),
+    // ];
 }

package/dist/types.d.ts

@@ -4,4 +4,5 @@ export interface GraphQLSafeGuardsOptions {
     preset?: SafeGuardPreset;
     depth?: number;
     complexity?: number;
+    ignoreIntrospection?: boolean;
 }

package/dist/utils/wrapIgnoreIntrospection.d.ts

@@ -0,0 +1,2 @@
+import { ValidationRule } from "graphql";
+export declare function wrapIgnoreIntrospection(rule: ValidationRule): ValidationRule;

package/dist/utils/wrapIgnoreIntrospection.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapIgnoreIntrospection = wrapIgnoreIntrospection;
+function wrapIgnoreIntrospection(rule) {
+    return (context) => {
+        const visitor = rule(context);
+        return {
+            Field(node) {
+                // Detecta introspection (__schema, __type)
+                if (node.name.value.startsWith("__")) {
+                    return false;
+                }
+                // Delegamos al visitor original si existe
+                const fieldVisitor = visitor === null || visitor === void 0 ? void 0 : visitor.Field;
+                if (typeof fieldVisitor === "function") {
+                    return fieldVisitor(node);
+                }
+            },
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphql-safe-guards",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Opinionated GraphQL security guards (depth + complexity) in one import",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/test/graphqlSafeGuards.test.ts

@@ -1,28 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { createSafeGuards } from "../src";
-
-describe("createSafeGuards", () => {
-  it("uses strict preset", () => {
-    const rules = createSafeGuards({ preset: "strict" });
-
-    expect(rules).toHaveLength(2);
-  });
-
-  it("allows overriding preset values", () => {
-    const rules = createSafeGuards({
-      preset: "strict",
-      depth: 10,
-    });
-
-    expect(rules).toHaveLength(2);
-  });
-
-  it("works without preset (backward compatible)", () => {
-    const rules = createSafeGuards({
-      depth: 4,
-      complexity: 20,
-    });
-
-    expect(rules).toHaveLength(2);
-  });
-});