Critical: Missing Constraint Validations in Parser/Compiler

[github-actions[bot]]

🔍 Schema Consistency Check - December 23, 2025

Overview

This analysis employed a NEW strategy (#25) focused on constraint enforcement and boundary testing. The analysis systematically examined all 71 JSON Schema constraint definitions (min/max, minItems/maxItems, minLength/maxLength) to verify they are properly enforced in the parser and compiler code.

Key Results:

• 4 critical missing validations found that could cause runtime errors or security issues
• 4 positive validations confirmed working correctly
• 71 total constrained fields identified in main schema
• New strategy proved highly effective with concrete, actionable findings

Full Report

Summary

• Inconsistencies Found: 4 critical, 0 moderate
• Categories Analyzed: Schema constraints, Parser validation, Compiler enforcement
• Strategy Used: NEW - Constraint Enforcement & Boundary Testing Analysis (Strategy Logs revamp. #25)
• New Strategy: YES
• Effectiveness: VERY HIGH - Found concrete missing validations

Critical Issues

1. Port Field - No Boundary Validation

Location: pkg/workflow/gateway.go:76-79

Schema Definition:

{
  "port": {
    "type": "integer",
    "minimum": 1,
    "maximum": 65535,
    "description": "Port number for the MCP gateway HTTP server (default: 8080)"
  }
}

Current Code:

port := config.Port
if port == 0 {
    port = DefaultMCPGatewayPort  // Only handles 0, not negative or > 65535
}

Issue:

• Schema declares valid port range as 1-65535
• Code only checks for zero (to apply default)
• Accepts invalid values: negative ports, port 0, ports > 65535

Impact: Could cause runtime failures when attempting to bind to invalid ports

Recommendation:

if port < 1 || port > 65535 {
    return fmt.Errorf("port must be between 1 and 65535, got %d", port)
}

2. Max-File-Size Field - No Boundary Validation

Location: pkg/workflow/repo_memory.go:160-168

Schema Definition:

{
  "max-file-size": {
    "type": "integer",
    "minimum": 1,
    "maximum": 104857600,
    "description": "Maximum size per file in bytes (default: 10240 = 10KB)"
  }
}

Current Code:

if maxFileSize, exists := memoryMap["max-file-size"]; exists {
    if sizeInt, ok := maxFileSize.(int); ok {
        entry.MaxFileSize = sizeInt  // ❌ No bounds checking
    } else if sizeFloat, ok := maxFileSize.(float64); ok {
        entry.MaxFileSize = int(sizeFloat)  // ❌ No bounds checking
    }
}

Issue:

• Schema declares valid range as 1 to 104,857,600 bytes (100 MB)
• Code parses value but performs no validation
• Accepts invalid values: 0, negative, or values exceeding 100 MB

Impact:

• Zero or negative: Could disable file size checking entirely
• Excessive values: Could allow memory exhaustion attacks

Recommendation:

if entry.MaxFileSize < 1 || entry.MaxFileSize > 104857600 {
    return fmt.Errorf("max-file-size must be between 1 and 104857600 bytes, got %d", entry.MaxFileSize)
}

3. Max-File-Count Field - No Boundary Validation

Location: pkg/workflow/repo_memory.go:171-179

Schema Definition:

{
  "max-file-count": {
    "type": "integer",
    "minimum": 1,
    "maximum": 1000,
    "description": "Maximum file count per commit (default: 100)"
  }
}

Current Code:

if maxFileCount, exists := memoryMap["max-file-count"]; exists {
    if countInt, ok := maxFileCount.(int); ok {
        entry.MaxFileCount = countInt  // ❌ No bounds checking
    } else if countFloat, ok := maxFileCount.(float64); ok {
        entry.MaxFileCount = int(countFloat)  // ❌ No bounds checking
    }
}

Issue:

• Schema declares valid range as 1 to 1,000 files
• Code parses value but performs no validation
• Accepts invalid values: 0, negative, or values exceeding 1,000

Impact:

• Zero or negative: Could disable file count limits
• Excessive values: Could allow resource exhaustion

Recommendation:

if entry.MaxFileCount < 1 || entry.MaxFileCount > 1000 {
    return fmt.Errorf("max-file-count must be between 1 and 1000, got %d", entry.MaxFileCount)
}

4. Retention-Days Field - No Boundary Validation

Location: pkg/workflow/repo_memory.go (field parsed but not validated)

Schema Definition:

{
  "retention-days": {
    "type": "integer",
    "minimum": 1,
    "maximum": 90,
    "description": "Number of days to retain uploaded artifacts (1-90 days)"
  }
}

Issue:

• Schema declares valid range as 1 to 90 days
• Field is referenced in code but no validation found
• Accepts invalid values: 0, negative, or values > 90 days

Impact: Could violate GitHub Actions retention policies or cause unexpected behavior

Recommendation:

if retentionDays < 1 || retentionDays > 90 {
    return fmt.Errorf("retention-days must be between 1 and 90, got %d", retentionDays)
}

Documentation Gaps

No documentation gaps identified in this analysis. The schema correctly documents all constraints. The issue is enforcement, not documentation.

However, consider adding $comment fields to critical constraints to remind developers:

{
  "port": {
    "type": "integer",
    "minimum": 1,
    "maximum": 65535,
    "$comment": "MUST validate: 1 <= port <= 65535. See pkg/workflow/gateway.go"
  }
}

Schema Improvements Needed

No schema changes needed. The schema is correct. The issue is that the parser/compiler code doesn't enforce the constraints defined in the schema.

However, consider adding $comment fields to critical constraints to remind developers:

{
  "port": {
    "type": "integer",
    "minimum": 1,
    "maximum": 65535,
    "$comment": "MUST validate: 1 <= port <= 65535. See pkg/workflow/gateway.go"
  }
}

Parser/Compiler Updates Required

Immediate Priority (Critical Bugs)

1. pkg/workflow/gateway.go - Add port validation (lines 76-79)
2. pkg/workflow/repo_memory.go - Add max-file-size validation (lines 160-168)
3. pkg/workflow/repo_memory.go - Add max-file-count validation (lines 171-179)
4. pkg/workflow/repo_memory.go - Add retention-days validation

Medium Priority (Systematic Improvements)

5. Create validation helpers - Add utility functions for common validation patterns:

   func validateIntRange(value, min, max int, fieldName string) error {
       if value < min || value > max {
           return fmt.Errorf("%s must be between %d and %d, got %d",
                             fieldName, min, max, value)
       }
       return nil
   }

6. Audit all 71 constrained fields - This analysis sampled 8 fields. A complete audit should verify all 71 constraints:

   • 30 fields with minimum constraints
   • 30 fields with maximum constraints
   • 15 fields with minLength constraints
   • 8 fields with minItems constraints
   • 2 fields with maxLength constraints
   • 1 field with minProperties constraint
   • 1 field with maxProperties constraint

7. Add boundary value tests - Create unit tests for each constrained field:

   • Test with minimum valid value
   • Test with maximum valid value
   • Test with below-minimum value (should fail)
   • Test with above-maximum value (should fail)
   • Test with zero (should fail if minimum > 0)
   • Test with negative (should fail if minimum > 0)

Workflow Violations

No workflow violations identified. The analysis focused on parser/compiler validation rather than actual workflow usage.

Validation Pattern Analysis

Pattern 1: Correct Length Validation ✅

Found in: pkg/workflow/frontmatter_extraction.go:489-490

if len(trackerID) < 8 {
    return "", fmt.Errorf("tracker-id must be at least 8 characters long (got %d)", len(trackerID))
}

Status: EXCELLENT - Validates minLength constraint correctly

Used for: tracker-id, schedule expressions, command names

Pattern 2: Missing Numeric Validation ❌

Found in: pkg/workflow/repo_memory.go:160-168, pkg/workflow/gateway.go:76-79

// Parses value but doesn't validate bounds
if sizeInt, ok := maxFileSize.(int); ok {
    entry.MaxFileSize = sizeInt  // No check if within 1 to 104857600
}

Status: PROBLEMATIC - Type coercion without boundary validation

Affects: port, max-file-size, max-file-count, retention-days

Pattern 3: Default-Only Validation ⚠️

Found in: pkg/workflow/gateway.go:76-79

port := config.Port
if port == 0 {
    port = DefaultMCPGatewayPort  // Only handles missing/zero case
}

Status: PARTIAL - Handles default case but not invalid values

Issue: Prevents zero but allows negative or excessive values

Recommendations

Immediate Actions (This Sprint)

1. ✅ Fix port validation in pkg/workflow/gateway.go
2. ✅ Fix max-file-size validation in pkg/workflow/repo_memory.go
3. ✅ Fix max-file-count validation in pkg/workflow/repo_memory.go
4. ✅ Fix retention-days validation in pkg/workflow/repo_memory.go

Short-term Actions (Next Sprint)

5. ✅ Create validation helper library with reusable range validation functions
6. ✅ Add unit tests for all boundary conditions on these 4 fields
7. ✅ Document validation patterns in CONTRIBUTING.md

Long-term Actions (Next Quarter)

8. ✅ Systematic constraint audit - Check all 71 constrained fields
9. ✅ Automated validation testing - CI checks for constraint enforcement
10. ✅ Schema-driven validation - Generate validation code from schema

Strategy Performance

Strategy Used: NEW - Constraint Enforcement & Boundary Testing Analysis (Strategy #25)

Methodology:

1. Extracted all 71 constraint definitions from main_workflow_schema.json using Python script
2. Identified constraint types: min/max (30 each), minLength (15), minItems (8), maxLength (2), minProperties/maxProperties (1 each)
3. Selected 8 representative fields spanning different constraint types
4. Traced each field from schema → parser → compiler
5. Verified validation logic for boundary conditions
6. Classified findings as: missing validation, partial validation, or correct validation

Findings: 4 critical missing validations, 4 positive correct validations

Effectiveness: VERY HIGH

• Found concrete, actionable bugs
• Identified systematic validation pattern gaps
• Provided specific code fixes for each issue
• Revealed larger architectural need for validation framework

Should Reuse: YES

• Run every 6-8 analyses to verify constraint enforcement
• Essential after adding new schema constraints
• Complements security-focused strategies (strategy-006)
• Pairs well with type coercion analysis (strategy-017)

Unique Value:

• First strategy focused specifically on constraint validation
• Revealed systematic gap in numeric boundary validation
• Found issues missed by field enumeration strategies
• Provides concrete code-level fixes, not just conceptual issues

Constraint Inventory

Total Constrained Fields: 71

By Constraint Type:

• minimum (integer lower bound): 30 fields
• maximum (integer upper bound): 30 fields
• minLength (string minimum length): 15 fields
• minItems (array minimum elements): 8 fields
• maxLength (string maximum length): 2 fields
• minProperties (object min properties): 1 field
• maxProperties (object max properties): 1 field

High-Risk Constraints (Need Validation):

1. Port ranges (1-65535)
2. File size limits (1-104857600 bytes)
3. File count limits (1-1000)
4. Retention periods (1-90 days)
5. Timeout values (1-∞ seconds)
6. Numeric identifiers with minimums

Well-Validated Constraints:

1. String length minimums (tracker-id, campaign, etc.)
2. Non-empty arrays (schedule, command.on)
3. Non-empty strings (event names, command names)

Next Steps

For Development Team

• Implement port validation in gateway.go
• Implement repo-memory constraint validation in repo_memory.go (3 fields)
• Create validation helper functions for numeric ranges
• Add boundary value unit tests for the 4 critical fields
• Review and implement validation for remaining 63 constrained fields

For Next Analysis Run

• Re-check these 4 fields to verify fixes implemented
• Expand analysis to all 71 constrained fields (not just 8)
• Check included_file_schema.json and mcp_config_schema.json for constraint issues
• Verify unit tests exist for all boundary conditions
• Check if validation helper library was created

For Strategy Evolution

• Consider creating automated tool to generate validation code from schema
• Explore JSON Schema validation libraries for Go that could enforce constraints
• Document this strategy in the "proven strategies" cache
• Pair this strategy with security audit (strategy-006) for comprehensive coverage

Files Analyzed

Schema Files:

• pkg/parser/schemas/main_workflow_schema.json - 71 constrained fields identified

Parser Files:

• pkg/parser/schedule_parser.go - ✅ Correct validation
• pkg/workflow/frontmatter_extraction.go - ✅ Correct validation

Compiler Files:

• pkg/workflow/gateway.go - ❌ Missing port validation
• pkg/workflow/repo_memory.go - ❌ Missing 3 constraint validations
• pkg/workflow/compiler_safe_outputs_prs.go - ⚠️ Uses defaults correctly but no explicit validation

References

• Schema constraints: pkg/parser/schemas/main_workflow_schema.json
• Port handling: pkg/workflow/gateway.go:76-79
• Repo memory config: pkg/workflow/repo_memory.go:160-200
• Tracker validation: pkg/workflow/frontmatter_extraction.go:489-490

---

Analysis Completed: 2025-12-23
Strategy: NEW - Constraint Enforcement & Boundary Testing (#25)
Critical Findings: 4
Effectiveness: VERY HIGH
Next Strategy Recommendation: Strategy-006 (Security Audit) or Strategy-004 (Cross-Schema Consistency)

AI generated by Schema Consistency Checker

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

Plan Created ✅

This audit has been broken down into actionable work items. A parent tracking issue and 5 sub-issues have been created to address the critical missing constraint validations.

Work breakdown:

1. Fix port validation (1-65535 range)
2. Fix max-file-size validation (1-104857600 bytes)
3. Fix max-file-count validation (1-1000 files)
4. Fix retention-days validation (1-90 days)
5. Create validation helpers and comprehensive boundary tests

All issues are tagged with bug and security labels. The parent issue links back to this discussion for full context.

---

AI generated by Planning Assistant for #7454

AI generated by Plan Command for discussion #7454