feat: GAP-43 - Implement Pydantic input validation for all VF endpoints

- Create validation models for ResourceSpec, Agent, Commitment, Match, Exchange
- Update all POST/PATCH endpoints to use Pydantic models
- Add field constraints: types, lengths, ranges, enums
- Prevent empty strings, validate URLs, enforce numeric ranges
- Remove raw dict parameters from all endpoints

Security: Prevents injection attacks, data corruption, and application crashes
Files: valueflows_node/app/models/requests/vf_objects.py and 5 endpoint files

Author: lizTheDeveloper

valueflows_node/app/api/vf/agents.py

@@ -12,6 +12,7 @@
 import uuid
 
 from ...models.vf.agent import Agent, AgentType
+from ...models.requests.vf_objects import AgentCreate
 from ...database import get_database
 from ...repositories.vf.agent_repo import AgentRepository
 from ...services.signing_service import SigningService
@@ -20,32 +21,33 @@
 
 
 @router.post("", response_model=dict)
-async def create_agent(agent_data: dict):
+async def create_agent(agent_data: AgentCreate):
     """
     Create a new agent.
 
-    Request body should contain:
-    - name: Agent name
-    - type: Agent type ("person", "group", or "place")
-    - description (optional): Description of agent
-    - image_url (optional): URL to image
-    - primary_location_id (optional): Primary location ID
-    - contact_info (optional): Contact information
+    GAP-43: Now uses Pydantic validation model.
+
+    Validates:
+    - Required fields present (name)
+    - Field types correct
+    - String lengths reasonable
+    - URLs have valid format
     """
     try:
-        # Generate ID if not provided
-        if "id" not in agent_data:
-            agent_data["id"] = f"agent:{uuid.uuid4()}"
+        # Convert validated Pydantic model to dict
+        data = agent_data.model_dump()
+
+        # Generate ID
+        data["id"] = f"agent:{uuid.uuid4()}"
 
         # Set timestamps
-        agent_data["created_at"] = datetime.now().isoformat()
+        data["created_at"] = datetime.now().isoformat()
 
-        # Handle field name mapping: "type" in request -> "agent_type" in model
-        if "type" in agent_data:
-            agent_data["agent_type"] = agent_data.pop("type")
+        # Map fields: "note" -> note is already correct in Pydantic model
+        # No mapping needed for agent create
 
         # Create Agent object
-        agent = Agent.from_dict(agent_data)
+        agent = Agent.from_dict(data)
 
         # Sign the agent
         # Use the node's signing service

valueflows_node/app/api/vf/commitments.py

@@ -6,6 +6,7 @@
 import uuid
 
 from ...models.vf.commitment import Commitment, CommitmentStatus
+from ...models.requests.vf_objects import CommitmentCreate, CommitmentUpdate
 from ...database import get_database
 from ...repositories.vf.commitment_repo import CommitmentRepository
 from ...services.vf_bundle_publisher import VFBundlePublisher
@@ -64,14 +65,26 @@ async def get_commitment(commitment_id: str):
 
 
 @router.post("/", response_model=dict)
-async def create_commitment(commitment_data: dict):
-    """Create a new commitment"""
+async def create_commitment(commitment_data: CommitmentCreate):
+    """
+    Create a new commitment.
+
+    GAP-43: Now uses Pydantic validation model.
+
+    Validates:
+    - Required fields present
+    - Field types correct
+    - Numeric ranges valid
+    - String lengths reasonable
+    """
     try:
-        if "id" not in commitment_data:
-            commitment_data["id"] = f"commitment:{uuid.uuid4()}"
-        commitment_data["created_at"] = datetime.now().isoformat()
+        # Convert validated Pydantic model to dict
+        data = commitment_data.model_dump()
 
-        commitment = Commitment.from_dict(commitment_data)
+        data["id"] = f"commitment:{uuid.uuid4()}"
+        data["created_at"] = datetime.now().isoformat()
+
+        commitment = Commitment.from_dict(data)
 
         db = get_database()
         db.connect()
@@ -93,8 +106,12 @@ async def create_commitment(commitment_data: dict):
 
 
 @router.patch("/{commitment_id}", response_model=dict)
-async def update_commitment(commitment_id: str, updates: dict):
-    """Update a commitment's status"""
+async def update_commitment(commitment_id: str, updates: CommitmentUpdate):
+    """
+    Update a commitment's status.
+
+    GAP-43: Now uses Pydantic validation model.
+    """
     try:
         db = get_database()
         db.connect()
@@ -104,13 +121,13 @@ async def update_commitment(commitment_id: str, updates: dict):
         if not commitment:
             raise HTTPException(status_code=404, detail="Commitment not found")
 
-        # Update status if provided
-        if "status" in updates:
-            commitment.status = CommitmentStatus(updates["status"])
+        # Convert validated Pydantic model to dict
+        update_dict = updates.model_dump(exclude_unset=True)
 
-        # Update fulfilled_by_event_id if provided
-        if "fulfilled_by_event_id" in updates:
-            commitment.fulfilled_by_event_id = updates["fulfilled_by_event_id"]
+        # Update fields from validated model
+        for key, value in update_dict.items():
+            if hasattr(commitment, key):
+                setattr(commitment, key, value)
 
         updated_commitment = commitment_repo.update(commitment)
 

valueflows_node/app/api/vf/exchanges.py

@@ -5,6 +5,7 @@
 import uuid
 
 from ...models.vf.exchange import Exchange
+from ...models.requests.vf_objects import ExchangeCreate
 from ...database import get_database
 from ...repositories.vf.exchange_repo import ExchangeRepository
 from ...services.vf_bundle_publisher import VFBundlePublisher
@@ -39,14 +40,25 @@ async def get_exchanges(status: str = None, agent_id: str = None):
 
 
 @router.post("/", response_model=dict)
-async def create_exchange(exchange_data: dict):
-    """Create a new exchange (from accepted match)"""
+async def create_exchange(exchange_data: ExchangeCreate):
+    """
+    Create a new exchange (from accepted match).
+
+    GAP-43: Now uses Pydantic validation model.
+
+    Validates:
+    - Required fields present (name)
+    - Field types correct
+    - String lengths reasonable
+    """
     try:
-        if "id" not in exchange_data:
-            exchange_data["id"] = f"exchange:{uuid.uuid4()}"
-        exchange_data["created_at"] = datetime.now().isoformat()
+        # Convert validated Pydantic model to dict
+        data = exchange_data.model_dump()
+
+        data["id"] = f"exchange:{uuid.uuid4()}"
+        data["created_at"] = datetime.now().isoformat()
 
-        exchange = Exchange.from_dict(exchange_data)
+        exchange = Exchange.from_dict(data)
 
         db = get_database()
         db.connect()

valueflows_node/app/api/vf/matches.py

@@ -6,6 +6,7 @@
 import sqlite3
 
 from ...models.vf.match import Match
+from ...models.requests.vf_objects import MatchCreate
 from ...database import get_database
 from ...repositories.vf.match_repo import MatchRepository
 from ...services.vf_bundle_publisher import VFBundlePublisher
@@ -48,14 +49,25 @@ async def get_matches(status: str = None, agent_id: str = None):
 
 
 @router.post("/", response_model=dict)
-async def create_match(match_data: dict):
-    """Create a new match (offer + need pairing)"""
+async def create_match(match_data: MatchCreate):
+    """
+    Create a new match (offer + need pairing).
+
+    GAP-43: Now uses Pydantic validation model.
+
+    Validates:
+    - Required fields present
+    - Field types correct
+    - Numeric ranges valid
+    """
     try:
-        if "id" not in match_data:
-            match_data["id"] = f"match:{uuid.uuid4()}"
-        match_data["created_at"] = datetime.now().isoformat()
+        # Convert validated Pydantic model to dict
+        data = match_data.model_dump()
+
+        data["id"] = f"match:{uuid.uuid4()}"
+        data["created_at"] = datetime.now().isoformat()
 
-        match = Match.from_dict(match_data)
+        match = Match.from_dict(data)
 
         # GAP-107: Check if either user has blocked the other
         block_repo = get_block_repo()

valueflows_node/app/api/vf/resource_specs.py

@@ -12,6 +12,7 @@
 import uuid
 
 from ...models.vf.resource_spec import ResourceSpec, ResourceCategory
+from ...models.requests.vf_objects import ResourceSpecCreate
 from ...database import get_database
 from ...repositories.vf.resource_spec_repo import ResourceSpecRepository
 from ...services.signing_service import SigningService
@@ -20,32 +21,35 @@
 
 
 @router.post("", response_model=dict)
-async def create_resource_spec(spec_data: dict):
+async def create_resource_spec(spec_data: ResourceSpecCreate):
     """
     Create a new resource specification.
 
-    Request body should contain:
-    - name: Resource spec name (e.g., "Tomatoes")
-    - category: Resource category (e.g., "food", "tools", "skills")
-    - unit (optional): Default unit of measure (e.g., "lbs", "hours", "items")
-    - description (optional): Description of resource spec
-    - subcategory (optional): Subcategory (e.g., "Vegetables")
-    - image_url (optional): URL to image
+    GAP-43: Now uses Pydantic validation model.
+
+    Validates:
+    - Required fields present (name, category)
+    - Field types correct
+    - String lengths reasonable
+    - Category is valid enum value
+    - URLs have valid format
     """
     try:
-        # Generate ID if not provided
-        if "id" not in spec_data:
-            spec_data["id"] = f"resource_spec:{uuid.uuid4()}"
+        # Convert validated Pydantic model to dict
+        data = spec_data.model_dump()
+
+        # Generate ID
+        data["id"] = f"resource_spec:{uuid.uuid4()}"
 
         # Set timestamps
-        spec_data["created_at"] = datetime.now().isoformat()
+        data["created_at"] = datetime.now().isoformat()
 
         # Handle field name mapping: "unit" in request -> "default_unit" in model
-        if "unit" in spec_data:
-            spec_data["default_unit"] = spec_data.pop("unit")
+        if "unit" in data:
+            data["default_unit"] = data.pop("unit")
 
         # Create ResourceSpec object
-        spec = ResourceSpec.from_dict(spec_data)
+        spec = ResourceSpec.from_dict(data)
 
         # Sign the resource spec
         # Use the node's signing service