feat: handle cyclic reference chains safely

Author: jonluca

lib/dereference.ts

@@ -318,7 +318,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
 
   // Check for circular references
   const directCircular = pointer.circular;
-  let circular = directCircular || parents.has(pointer.value);
+  let circular = directCircular || pointer.chainCircular || parents.has(pointer.value);
   if (circular) {
     foundCircularReference(path, $refs, options);
   }
@@ -352,7 +352,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
     dereferencedValue = $ref;
   }
 
-  if (directCircular) {
+  if (directCircular && dereferencedValue !== $ref) {
     // The pointer is a DIRECT circular reference (i.e. it references itself).
     // So replace the $ref path with the absolute path from the JSON Schema root
     dereferencedValue.$ref = pathFromRoot;

lib/options.ts

@@ -103,6 +103,7 @@ export interface DereferenceOptions {
    * The maximum recursion depth for dereferencing nested schemas.
    * If the schema nesting exceeds this depth, a RangeError will be thrown
    * with a descriptive message instead of crashing with a stack overflow.
+   * This limit also applies to `$ref` resolution chains.
    *
    * Default: 500
    */

lib/pointer.ts

@@ -55,6 +55,10 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    * Indicates whether the pointer references itself.
    */
   circular: boolean;
+  /**
+   * Indicates whether the pointer encountered a cycle elsewhere in its reference chain.
+   */
+  chainCircular: boolean;
   /**
    * The number of indirect references that were traversed to resolve the value.
    * Resolving a single pointer may require resolving multiple $Refs.
@@ -74,6 +78,8 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     this.circular = false;
 
+    this.chainCircular = false;
+
     this.indirections = 0;
   }
 
@@ -90,7 +96,13 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    * the {@link Pointer#$ref} and {@link Pointer#path} will reflect the resolution path
    * of the resolved value.
    */
-  resolve(obj: S, options?: O, pathFromRoot?: string) {
+  resolve(
+    obj: S,
+    options?: O,
+    pathFromRoot?: string,
+    visitedRefPaths = new Set<string>(),
+    resolveFinalReference = true,
+  ) {
     const tokens = Pointer.parse(this.path, this.originalPath);
     const found: string[] = [];
 
@@ -108,15 +120,17 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
       // This prevents false circular detection when e.g. a root schema has both
       // $ref: "#/$defs/Foo" and $defs: { Foo: {...} } as siblings.
       const wasCircular = this.circular;
+      const wasChainCircular = this.chainCircular;
       const isExtendedRef = $Ref.isExtended$Ref(this.value);
-      if (resolveIf$Ref(this, options, pathFromRoot)) {
+      if (resolveIf$Ref(this, options, pathFromRoot, visitedRefPaths)) {
         // The $ref path has changed, so append the remaining tokens to the path
         this.path = Pointer.join(this.path, tokens.slice(i));
-      } else if (!wasCircular && this.circular && isExtendedRef) {
+      } else if (isExtendedRef) {
         // resolveIf$Ref set circular=true on an extended $ref during token walking.
         // Since we still have tokens to process, the object should be walked by its
         // properties, not treated as a circular self-reference.
-        this.circular = false;
+        this.circular = wasCircular;
+        this.chainCircular = wasChainCircular;
       }
 
       const token = tokens[i];
@@ -134,6 +148,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
           }
         }
         if (didFindSubstringSlashMatch) {
+          this.chainCircular = wasChainCircular;
           continue;
         }
 
@@ -144,6 +159,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
           // We use a `null` symbol for internal tracking to differentiate between a general `null`
           // value and our expected `null` value.
           this.value = nullSymbol;
+          this.chainCircular = wasChainCircular;
           continue;
         }
 
@@ -160,6 +176,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
         this.value = this.value[token];
       }
 
+      this.chainCircular = wasChainCircular;
       found.push(token);
       if (this.$ref.dynamicIdScope) {
         this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
@@ -168,8 +185,20 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // Resolve the final value
     const finalResolutionBase = this.$ref.dynamicIdScope ? this.scopeBase : this.path;
-    if (!this.value || (this.value.$ref && url.resolve(finalResolutionBase, this.value.$ref) !== pathFromRoot)) {
-      resolveIf$Ref(this, options, pathFromRoot);
+    if (resolveFinalReference) {
+      const finalRefPath = this.value?.$ref ? url.resolve(finalResolutionBase, this.value.$ref) : undefined;
+      const canonicalPathFromRoot =
+        typeof pathFromRoot === "string" ? url.resolve(this.$ref.$refs._root$Ref.path!, pathFromRoot) : pathFromRoot;
+
+      if (
+        $Ref.isAllowed$Ref(this.value, options) &&
+        finalRefPath === canonicalPathFromRoot &&
+        finalRefPath !== this.path
+      ) {
+        this.chainCircular = true;
+      } else if (!this.value || finalRefPath) {
+        resolveIf$Ref(this, options, pathFromRoot, visitedRefPaths);
+      }
     }
 
     return this;
@@ -305,32 +334,74 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
  * @returns - Returns `true` if the resolution path changed
  */
 function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-  pointer: Pointer,
+  pointer: Pointer<S, O>,
   options: O | undefined,
   pathFromRoot?: string,
+  visitedRefPaths = new Set<string>(),
 ) {
-  // Is the value a JSON reference? (and allowed?)
+  let pathChanged = false;
+  let currentPathFromRoot = pathFromRoot;
+  const addedPaths: string[] = [];
+
+  try {
+    // Pure reference chains can be followed iteratively. Extended refs still use
+    // the existing one-hop behavior because their values must be merged on return.
+    while ($Ref.isAllowed$Ref(pointer.value, options)) {
+      const extended = $Ref.isExtended$Ref(pointer.value);
+      const sourceValue = pointer.value;
+      const parentPath = pointer.path;
+      const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
+      const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
+
+      if ($refPath === pointer.path && !isRootPath(currentPathFromRoot)) {
+        // The value is a reference to itself, so there's nothing to do.
+        pointer.circular = true;
+        pointer.chainCircular = true;
+        return pathChanged;
+      }
 
-  if ($Ref.isAllowed$Ref(pointer.value, options)) {
-    const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
-    const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
+      const canonicalPathFromRoot =
+        typeof currentPathFromRoot === "string"
+          ? url.resolve(pointer.$ref.$refs._root$Ref.path!, currentPathFromRoot)
+          : currentPathFromRoot;
+      if ($refPath === canonicalPathFromRoot && $refPath !== pointer.path) {
+        pointer.chainCircular = true;
+        return pathChanged;
+      }
 
-    if ($refPath === pointer.path && !isRootPath(pathFromRoot)) {
-      // The value is a reference to itself, so there's nothing to do.
-      pointer.circular = true;
-    } else {
-      const resolved = pointer.$ref.$refs._resolve($refPath, pointer.path, options);
+      if (visitedRefPaths.has($refPath)) {
+        pointer.chainCircular = true;
+        return pathChanged;
+      }
+
+      const maxDepth = options?.dereference?.maxDepth ?? 500;
+      if (visitedRefPaths.size >= maxDepth) {
+        throw new RangeError(
+          `Maximum dereference depth (${maxDepth}) exceeded at ${pointer.path}. ` +
+            `This likely indicates an extremely deep or recursive schema. ` +
+            `You can increase this limit with the dereference.maxDepth option.`,
+        );
+      }
+
+      visitedRefPaths.add($refPath);
+      addedPaths.push($refPath);
+
+      const resolved = pointer.$ref.$refs._resolve($refPath, parentPath, options, visitedRefPaths, extended);
       if (resolved === null) {
-        return false;
+        return pathChanged;
       }
 
       pointer.indirections += resolved.indirections + 1;
+      pointer.chainCircular ||= resolved.circular || resolved.chainCircular;
 
-      if ($Ref.isExtended$Ref(pointer.value)) {
+      if (extended) {
         // This JSON reference "extends" the resolved value, rather than simply pointing to it.
         // So the resolved path does NOT change.  Just the value does.
-        pointer.value = $Ref.dereference(pointer.value, resolved.value, options);
-        return false;
+        if (pointer.chainCircular) {
+          return pathChanged;
+        }
+        pointer.value = $Ref.dereference(sourceValue, resolved.value, options);
+        return pathChanged;
       } else {
         // Resolve the reference
         pointer.$ref = resolved.$ref;
@@ -339,13 +410,18 @@ function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
         // `pointer.$ref.path` is already the canonical location of the resolved resource.
         // Re-applying the resource's own `$id` here would duplicate nested path segments
         // such as `nested/nested/foo.json`.
-        pointer.scopeBase = pointer.$ref.path!;
+        pointer.scopeBase = resolved.scopeBase;
+        currentPathFromRoot = parentPath;
+        pathChanged = true;
       }
+    }
 
-      return true;
+    return pathChanged;
+  } finally {
+    for (const path of addedPaths) {
+      visitedRefPaths.delete(path);
     }
   }
-  return undefined;
 }
 export default Pointer;
 

lib/ref.ts

@@ -120,12 +120,21 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    * @param options
    * @param friendlyPath - The original user-specified path (used for error messages)
    * @param pathFromRoot - The path of `obj` from the schema root
+   * @param visitedRefPaths - the active paths in the current reference chain
+   * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
    * @returns
    */
-  resolve(path: string, options?: O, friendlyPath?: string, pathFromRoot?: string) {
+  resolve(
+    path: string,
+    options?: O,
+    friendlyPath?: string,
+    pathFromRoot?: string,
+    visitedRefPaths?: Set<string>,
+    resolveFinalReference = true,
+  ) {
     const pointer = new Pointer<S, O>(this, path, friendlyPath);
     try {
-      const resolved = pointer.resolve(this.value, options, pathFromRoot);
+      const resolved = pointer.resolve(this.value, options, pathFromRoot, visitedRefPaths, resolveFinalReference);
       if (resolved.value === nullSymbol) {
         resolved.value = null;
       }

lib/refs.ts

@@ -155,18 +155,26 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    * @param path - The path being resolved, optionally with a JSON pointer in the hash
    * @param pathFromRoot - The path of `obj` from the schema root
    * @param [options]
+   * @param visitedRefPaths - the active paths in the current reference chain
+   * @param resolveFinalReference - whether to follow a `$ref` at the resolved value
    * @returns
    * @protected
    */
-  _resolve(path: string, pathFromRoot: string, options?: O) {
+  _resolve(
+    path: string,
+    pathFromRoot: string,
+    options?: O,
+    visitedRefPaths?: Set<string>,
+    resolveFinalReference = true,
+  ) {
     const absPath = url.resolve(this._root$Ref.path!, path);
     const $ref = this._getRef(absPath);
 
     if (!$ref) {
       throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
     }
 
-    return $ref.resolve(absPath, options, path, pathFromRoot);
+    return $ref.resolve(absPath, options, path, pathFromRoot, visitedRefPaths, resolveFinalReference);
   }
 
   /**

test/specs/circular-chain/circular-chain.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import $RefParser from "../../../lib/index.js";
+
+describe("Circular $ref chains", () => {
+  for (const length of [3, 4]) {
+    it(`detects a cycle of length ${length} without overflowing`, async () => {
+      const input = createCircularSchema(length);
+      const parser = new $RefParser();
+
+      const result = await parser.dereference(input);
+
+      expect(result).to.be.an("object");
+      expect(parser.$refs.circular).to.equal(true);
+    });
+  }
+
+  it("honors dereference.circular=false", async () => {
+    const parser = new $RefParser();
+
+    await expect(
+      parser.dereference(createCircularSchema(3), {
+        dereference: { circular: false },
+      }),
+    ).rejects.toThrowError(ReferenceError);
+  });
+
+  it("bundles a multi-reference cycle without overflowing", async () => {
+    const parser = new $RefParser();
+
+    const result = await parser.bundle(createCircularSchema(3));
+
+    expect(result).to.be.an("object");
+  });
+});
+
+function createCircularSchema(length: number) {
+  const schemas: Record<string, { $ref: string }> = {};
+  for (let index = 0; index < length; index++) {
+    schemas[`node${index}`] = {
+      $ref: `#/components/schemas/node${(index + 1) % length}`,
+    };
+  }
+
+  return {
+    components: { schemas },
+    entry: { $ref: "#/components/schemas/node0" },
+  };
+}

test/specs/dereference-max-depth/dereference-max-depth.spec.ts

@@ -43,6 +43,29 @@ describe("Dereference max depth", () => {
     expect(result.type).toBe("object");
   });
 
+  it("should apply max depth to reference chains", async () => {
+    const parser = new $RefParser();
+    await parser.resolve(createReferenceChain(5_000));
+
+    expect(() => parser.$refs.get("#/entry")).to.throw(/Maximum dereference depth \(500\)/);
+    expect(() =>
+      parser.$refs.get("#/entry", {
+        dereference: { maxDepth: 1_000 },
+      }),
+    ).to.throw(/Maximum dereference depth \(1000\)/);
+
+    expect(
+      parser.$refs.get("#/entry", {
+        dereference: { maxDepth: 6_000 },
+      }),
+    ).to.deep.equal({ type: "string" });
+
+    const dereferenced = await new $RefParser().dereference(createReferenceChain(600), {
+      dereference: { maxDepth: 1_000 },
+    });
+    expect(dereferenced.entry).to.deep.equal({ type: "string" });
+  });
+
   it("should dereference normally when within max depth", async () => {
     const schema = {
       type: "object",
@@ -58,3 +81,16 @@ describe("Dereference max depth", () => {
     expect(result.properties.name.type).toBe("string");
   });
 });
+
+function createReferenceChain(length: number) {
+  const definitions: Record<string, { $ref: string } | { type: string }> = {};
+  for (let index = 0; index < length; index++) {
+    definitions[`node${index}`] =
+      index === length - 1 ? { type: "string" } : { $ref: `#/definitions/node${index + 1}` };
+  }
+
+  return {
+    definitions,
+    entry: { $ref: "#/definitions/node0" },
+  };
+}