@ts-graphviz/ast 3.0.4 → 3.0.5-next-dc3ef34316f5642c416711cb6a50704dbef7bb64

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @ts-graphviz/ast
 
+## 3.0.5-next-dc3ef34316f5642c416711cb6a50704dbef7bb64
+
+### Patch Changes
+
+- [#1533](https://github.com/ts-graphviz/ts-graphviz/pull/1533) [`ed770be`](https://github.com/ts-graphviz/ts-graphviz/commit/ed770be7fffc93b9171198c9a84270df7477185d) Thanks [@kamiazya](https://github.com/kamiazya)! - Add memory exhaustion protection with input size and AST node count limits
+
+  Addresses security vulnerability where extremely large inputs or inputs with excessive elements could cause memory exhaustion, leading to application crashes and potential DoS attacks.
+
+  ## Security Enhancements
+
+  ### Input Size Limit
+
+  - Added `maxInputSize` option to `parse()` function (default: 10MB)
+  - Validates input size before parsing to prevent memory exhaustion from extremely large DOT files
+  - Configurable limit allows flexibility for legitimate large graphs
+  - Can be disabled by setting to 0 (not recommended for untrusted inputs)
+
+  ### AST Node Count Limit
+
+  - Added `maxASTNodes` option to `parse()` function (default: 100,000 nodes)
+  - Tracks and limits the number of AST nodes created during parsing
+  - Prevents memory exhaustion from inputs with excessive elements
+  - Configurable limit for complex graphs when needed
+  - Can be disabled by setting to 0 (not recommended for untrusted inputs)
+
+  ## Changes
+
+  ### API Updates
+
+  - `CommonParseOptions` interface extended with `maxInputSize` and `maxASTNodes` options
+  - `Builder` class enhanced with node counting and validation
+  - `parse()` function validates input size before parsing
+  - Parser grammar updated to pass limits to Builder
+
+  ### Error Handling
+
+  - Input size violations throw `DotSyntaxError` with descriptive messages
+  - AST node count violations throw `DotSyntaxError` with actionable guidance
+  - Error messages include current values and suggestions for resolution
+
+  ### Testing
+
+  - Comprehensive test coverage for both limits
+  - Tests for normal usage, boundary conditions, and limit violations
+  - Tests for custom limit values and disabling limits
+  - All 62 parser tests passing
+
+  ### Documentation
+
+  - Updated `SECURITY.md` with detailed security protection information
+  - Added usage examples and best practices
+  - Documented recommendations for untrusted input handling
+
+  ## Security Impact
+
+  - Prevents DoS attacks via extremely large DOT files (hundreds of MB)
+  - Prevents memory exhaustion from inputs with tens of thousands of elements
+  - Default limits protect normal use cases while allowing customization
+  - Complements existing protections (HTML nesting depth, edge chain depth)
+  - Provides defense-in-depth security strategy
+
+- [#1532](https://github.com/ts-graphviz/ts-graphviz/pull/1532) [`dc3ef34`](https://github.com/ts-graphviz/ts-graphviz/commit/dc3ef34316f5642c416711cb6a50704dbef7bb64) Thanks [@dependabot](https://github.com/apps/dependabot)! - build(deps-dev): bump vite from 7.0.2 to 7.0.8 in the npm_and_yarn group across 1 directory
+
+- Updated dependencies [[`dc3ef34`](https://github.com/ts-graphviz/ts-graphviz/commit/dc3ef34316f5642c416711cb6a50704dbef7bb64)]:
+  - @ts-graphviz/common@3.0.4-next-dc3ef34316f5642c416711cb6a50704dbef7bb64
+
 ## 3.0.4
 
 ### Patch Changes

package/README.md

@@ -73,18 +73,47 @@ The `parse` function accepts an optional second argument for configuration:
 ```ts
 import { parse } from "@ts-graphviz/ast";
 
-// Parse with custom HTML nesting depth limit
+// Parse with custom security limits
 const ast = parse(dotString, {
-  startRule: 'Dot',  // Specify the starting rule (default: 'Dot')
-  maxHtmlNestingDepth: 200  // Set maximum HTML nesting depth (default: 100)
+  startRule: 'Dot',              // Specify the starting rule (default: 'Dot')
+  maxHtmlNestingDepth: 200,      // Maximum HTML nesting depth (default: 100)
+  maxEdgeChainDepth: 2000,       // Maximum edge chain depth (default: 1000)
+  maxInputSize: 20971520,        // Maximum input size in bytes (default: 10MB)
+  maxASTNodes: 200000            // Maximum AST nodes (default: 100,000)
 });
 ```
 
+**Available Options**:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `startRule` | `'Dot'` | Starting grammar rule for parsing |
+| `maxHtmlNestingDepth` | `100` | Maximum depth of nested HTML-like structures |
+| `maxEdgeChainDepth` | `1000` | Maximum depth of chained edges (e.g., `a -> b -> c -> ...`) |
+| `maxInputSize` | `10485760` (10MB) | Maximum input size in bytes |
+| `maxASTNodes` | `100000` | Maximum number of AST nodes to create |
+
 **Security Note**:
-- The `maxHtmlNestingDepth` option limits the depth of nested HTML-like structures in DOT files to prevent stack overflow attacks
-- The default limit of 100 is sufficient for normal use cases (typically <10 levels)
-- HTML-like labels are GraphViz DOT syntax, not browser HTML
-- For processing untrusted DOT files, see the validation guide in `@ts-graphviz/adapter` documentation
+
+These limits protect against denial-of-service attacks:
+
+- **`maxHtmlNestingDepth`**: Prevents stack overflow from deeply nested HTML-like structures
+  - Normal use cases: typically <10 levels
+  - HTML-like labels are GraphViz DOT syntax, not browser HTML
+
+- **`maxEdgeChainDepth`**: Prevents stack overflow from deeply chained edges
+  - Example dangerous input: `a -> b -> c -> ... -> z (1000+ nodes)`
+
+- **`maxInputSize`**: Prevents memory exhaustion from extremely large files
+  - Default 10MB is sufficient for most legitimate graphs
+  - Can be increased for known large graphs or disabled with `0` (not recommended for untrusted input)
+
+- **`maxASTNodes`**: Prevents memory exhaustion from inputs with excessive elements
+  - Each DOT element creates multiple AST nodes
+  - Example: A single node statement (`node1;`) creates ~2-3 AST nodes
+  - Can be disabled with `0` (not recommended for untrusted input)
+
+**Important**: When processing untrusted DOT files (e.g., user uploads), keep these limits enabled with conservative values appropriate for your environment. For additional validation of untrusted content, see the validation guide in [@ts-graphviz/adapter documentation](../adapter/README.md#security-considerations).
 
 ### Generating DOT Language
 

package/lib/ast.d.ts

@@ -66,6 +66,23 @@ export declare interface ASTCommonPropaties {
  */
 export declare type ASTNode = LiteralASTNode | DotASTNode | GraphASTNode | AttributeASTNode | CommentASTNode | AttributeListASTNode | NodeRefASTNode | NodeRefGroupASTNode | EdgeASTNode | NodeASTNode | SubgraphASTNode;
 
+/**
+ * Error thrown when the AST node count exceeds the maximum allowed limit.
+ * This error is thrown during parsing to prevent memory exhaustion attacks.
+ *
+ * @group Create AST
+ */
+export declare class ASTNodeCountExceededError extends Error {
+    nodeCount: number;
+    maxNodes: number;
+    /**
+     * Constructor
+     * @param nodeCount - The current node count when the limit was exceeded
+     * @param maxNodes - The maximum allowed node count
+     */
+    constructor(nodeCount: number, maxNodes: number);
+}
+
 /**
  * ASTToModel is a type that determines a model type from an AST.
  *
@@ -115,6 +132,8 @@ export declare interface AttributeListASTPropaties extends ASTCommonPropaties {
  */
 export declare class Builder implements ASTBuilder {
     private options?;
+    private nodeCount;
+    private maxNodes;
     /* Excluded from this release type: getLocation */
     /**
      * Constructor of Builder
@@ -128,8 +147,10 @@ export declare class Builder implements ASTBuilder {
      * @param props - Properties of the {@link ASTNode}
      * @param children - Children of the {@link ASTNode}
      * @returns An {@link ASTNode}
+     * @throws {ASTNodeCountExceededError} if the maximum number of AST nodes is exceeded
      */
     createElement<T extends ASTNode>(type: T['type'], props: any, children?: ASTChildNode<T>[]): T;
+    /* Excluded from this release type: resetNodeCount */
 }
 
 /**
@@ -143,6 +164,12 @@ export declare interface BuilderOptions {
      * It is used to specify the location of the builder.
      */
     locationFunction: () => FileRange;
+    /**
+     * Maximum allowed number of AST nodes to create.
+     * Default is 100000. Set to 0 to disable this limit.
+     * @default 100000
+     */
+    maxASTNodes?: number;
 }
 
 /**
@@ -201,6 +228,20 @@ export declare interface CommonParseOptions {
      * @default 1000
      */
     maxEdgeChainDepth?: number;
+    /**
+     * maxInputSize (optional): Maximum allowed input size in bytes.
+     * Default is 10MB (10485760 bytes). This limit prevents memory exhaustion from extremely large inputs.
+     * Set to 0 to disable this limit (not recommended for untrusted inputs).
+     * @default 10485760
+     */
+    maxInputSize?: number;
+    /**
+     * maxASTNodes (optional): Maximum allowed number of AST nodes to create during parsing.
+     * Default is 100000. This limit prevents memory exhaustion from inputs with excessive elements.
+     * Set to 0 to disable this limit (not recommended for untrusted inputs).
+     * @default 100000
+     */
+    maxASTNodes?: number;
 }
 
 /**

package/lib/ast.js

@@ -1,4 +1,20 @@
 import { isNodeModel, isForwardRefNode, createModelsContext } from "@ts-graphviz/common";
+class ASTNodeCountExceededError extends Error {
+  /**
+   * Constructor
+   * @param nodeCount - The current node count when the limit was exceeded
+   * @param maxNodes - The maximum allowed node count
+   */
+  constructor(nodeCount, maxNodes) {
+    super(
+      `AST node count (${nodeCount}) exceeds maximum allowed (${maxNodes}). Consider increasing 'maxASTNodes' option or simplifying the input.`
+    );
+    this.nodeCount = nodeCount;
+    this.maxNodes = maxNodes;
+    this.name = "ASTNodeCountExceededError";
+  }
+}
+const DEFAULT_MAX_AST_NODES = 1e5;
 class Builder {
   /**
    * Constructor of Builder
@@ -6,7 +22,10 @@ class Builder {
    */
   constructor(options) {
     this.options = options;
+    this.maxNodes = options?.maxASTNodes ?? DEFAULT_MAX_AST_NODES;
   }
+  nodeCount = 0;
+  maxNodes;
   /**
    * Get the current file range or null
    * @internal
@@ -21,8 +40,13 @@ class Builder {
    * @param props - Properties of the {@link ASTNode}
    * @param children - Children of the {@link ASTNode}
    * @returns An {@link ASTNode}
+   * @throws {ASTNodeCountExceededError} if the maximum number of AST nodes is exceeded
    */
   createElement(type, props, children = []) {
+    this.nodeCount++;
+    if (this.maxNodes > 0 && this.nodeCount > this.maxNodes) {
+      throw new ASTNodeCountExceededError(this.nodeCount, this.maxNodes);
+    }
     return {
       location: this.getLocation(),
       ...props,
@@ -30,6 +54,13 @@ class Builder {
       children
     };
   }
+  /**
+   * Reset the node count. Used internally by the parser between parse invocations.
+   * @internal
+   */
+  resetNodeCount() {
+    this.nodeCount = 0;
+  }
 }
 const createElement = Builder.prototype.createElement.bind(new Builder());
 class peg$SyntaxError extends SyntaxError {
@@ -2718,8 +2749,16 @@ function peg$parse(input, options) {
   let htmlNestingDepth = 0;
   let edgeChainDepth = 0;
   const b = new Builder({
-    locationFunction: location
+    locationFunction: location,
+    maxASTNodes: options.maxASTNodes
   });
+  function resetState() {
+    b.resetNodeCount();
+    htmlNestingDepth = 0;
+    edgeChainDepth = 0;
+    edgeops.length = 0;
+  }
+  resetState();
   peg$result = peg$startRuleFunction();
   const peg$success = peg$result !== peg$FAILED && peg$currPos === input.length;
   function peg$throw() {
@@ -2752,14 +2791,32 @@ function peg$parse(input, options) {
     peg$throw();
   }
 }
+const DEFAULT_MAX_INPUT_SIZE = 10 * 1024 * 1024;
 function parse(input, options) {
-  const { startRule, filename, maxHtmlNestingDepth, maxEdgeChainDepth } = options ?? {};
+  const {
+    startRule,
+    filename,
+    maxHtmlNestingDepth,
+    maxEdgeChainDepth,
+    maxInputSize,
+    maxASTNodes
+  } = options ?? {};
+  const inputSizeLimit = maxInputSize ?? DEFAULT_MAX_INPUT_SIZE;
+  if (inputSizeLimit > 0) {
+    const inputBytes = new TextEncoder().encode(input).length;
+    if (inputBytes > inputSizeLimit) {
+      throw new DotSyntaxError(
+        `Input size (${inputBytes} bytes) exceeds maximum allowed size (${inputSizeLimit} bytes). Consider increasing 'maxInputSize' option or reducing the input size.`
+      );
+    }
+  }
   try {
     return peg$parse(input, {
       startRule,
       filename,
       maxHtmlNestingDepth,
-      maxEdgeChainDepth
+      maxEdgeChainDepth,
+      maxASTNodes
     });
   } catch (e) {
     if (e instanceof peg$SyntaxError) {
@@ -2767,6 +2824,11 @@ function parse(input, options) {
         cause: e
       });
     }
+    if (e instanceof ASTNodeCountExceededError) {
+      throw new DotSyntaxError(e.message, {
+        cause: e
+      });
+    }
     throw new Error("Unexpected parse error", {
       cause: e
     });
@@ -3108,7 +3170,7 @@ function convertComment(value, kind) {
 }
 function convertClusterChildren(context, model) {
   return Array.from(
-    function* () {
+    (function* () {
       for (const [key, value] of model.values) {
         yield convertAttribute(key, value);
       }
@@ -3138,7 +3200,7 @@ function convertClusterChildren(context, model) {
         }
         yield context.convert(edge);
       }
-    }()
+    })()
   );
 }
 const AttributeListPlugin = {
@@ -3605,6 +3667,7 @@ function toModel(ast, options) {
   return new ToModelConverter(options).convert(ast);
 }
 export {
+  ASTNodeCountExceededError,
   Builder,
   DotSyntaxError,
   FromModelConverter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-graphviz/ast",
-  "version": "3.0.4",
+  "version": "3.0.5-next-dc3ef34316f5642c416711cb6a50704dbef7bb64",
   "description": "Graphviz AST(Abstract Syntax Tree) Utilities",
   "keywords": [],
   "homepage": "https://github.com/ts-graphviz/ts-graphviz#readme",
@@ -33,12 +33,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@ts-graphviz/common": "^3.0.3"
+    "@ts-graphviz/common": "^3.0.4-next-dc3ef34316f5642c416711cb6a50704dbef7bb64"
   },
   "devDependencies": {
     "peggy": "^5.0.6",
     "typescript": "^5.8.2",
-    "vite": "^7.0.2",
+    "vite": "^7.0.8",
     "vite-plugin-dts": "^4.5.3"
   },
   "engines": {