Source code for vcon.extensions.lawful_basis.validation

"""
Validation for Lawful Basis Extension

This module implements validation logic for lawful basis attachments
and extension usage according to the draft specification.
"""

from typing import Dict, List, Any, Optional
import logging
from datetime import datetime, timezone
from ..base import ExtensionValidator, ValidationResult
from ...body import decode_body
from .attachment import (
    LawfulBasisAttachment,
    LawfulBasisType,
    ProofType,
    HashAlgorithm,
    CanonicalizationMethod
)

logger = logging.getLogger(__name__)


[docs]class LawfulBasisValidationError(Exception): """Base exception for lawful basis validation errors.""" pass
[docs]class LawfulBasisExpiredError(LawfulBasisValidationError): """Raised when lawful basis has expired.""" pass
[docs]class PermissionDeniedError(LawfulBasisValidationError): """Raised when permission is explicitly denied.""" pass
[docs]class LawfulBasisMissingError(LawfulBasisValidationError): """Raised when no valid lawful basis is found.""" pass
[docs]class ProofVerificationError(LawfulBasisValidationError): """Raised when proof mechanisms fail validation.""" pass
[docs]class ContentHashMismatchError(LawfulBasisValidationError): """Raised when content hash validation fails.""" pass
def _fields(value: Any) -> Dict[str, Any]: """A malformed (non-object) sub-object is checked as an empty one.""" return value if isinstance(value, dict) else {} def _member(value: Any, allowed: Any) -> bool: try: return value in allowed except TypeError: # unhashable, e.g. a list return False def _parse_timestamp(value: Any) -> Optional[datetime]: """ISO 8601 timestamp, or None. A value with no offset is read as UTC.""" if not isinstance(value, str): return None try: parsed = datetime.fromisoformat(value.replace('Z', '+00:00')) except ValueError: return None return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
[docs]class LawfulBasisValidator(ExtensionValidator): """Validator for lawful basis extension.""" def __init__(self): self.supported_lawful_bases = {basis.value for basis in LawfulBasisType} self.supported_proof_types = {proof.value for proof in ProofType} self.supported_hash_algorithms = {alg.value for alg in HashAlgorithm} self.supported_canonicalization = {canon.value for canon in CanonicalizationMethod}
[docs] def validate_attachment(self, attachment: Dict[str, Any]) -> ValidationResult: """Validate a lawful basis attachment.""" result = ValidationResult(True) # Check attachment purpose if attachment.get("purpose") != "lawful_basis": result.add_error("Invalid attachment purpose for lawful basis extension") return result # Check encoding if attachment.get("encoding") != "json": result.add_error("Lawful basis attachment must use 'json' encoding") # Core-05 scope (4.6.3 to 4.6.5). Warnings, so a bare body built by # create_lawful_basis_attachment() can still be checked before it is # placed in a vCon; Vcon.is_valid() enforces party and dialog/session. if "party" not in attachment: result.add_warning("Lawful basis attachment has no party (core-05 requires it)") if "session" not in attachment: result.add_warning( "Lawful basis attachment has no session; core-05 scopes a basis to Sessions" + ("" if "dialog" in attachment else " and an attachment needs dialog or session") ) # Validate body structure. Accept both the -04 shape (body already # the decoded object) and a legacy JSON-string body. body = decode_body(attachment) if not isinstance(body, dict): result.add_error("Lawful basis attachment body must be a dictionary") return result # Validate required fields body_result = self._validate_lawful_basis_body(body) result.warnings.extend(body_result.warnings) if not body_result.is_valid: result.errors.extend(body_result.errors) result.is_valid = False return result
[docs] def validate_extension_usage(self, vcon_dict: Dict[str, Any]) -> ValidationResult: """Validate lawful basis extension usage in a vCon.""" result = ValidationResult(True) # Check if extension is declared extensions = vcon_dict.get("extensions", []) if "lawful_basis" not in extensions: result.add_warning("Lawful basis extension not declared in extensions array") # Validate all lawful basis attachments attachments = vcon_dict.get("attachments", []) lawful_basis_attachments = [ att for att in attachments if att.get("purpose") == "lawful_basis" ] for i, attachment in enumerate(lawful_basis_attachments): att_result = self.validate_attachment(attachment) if not att_result.is_valid: result.add_error(f"Lawful basis attachment {i}: {', '.join(att_result.errors)}") result.is_valid = False result.warnings.extend([f"Attachment {i}: {w}" for w in att_result.warnings]) return result
def _validate_lawful_basis_body(self, body: Dict[str, Any]) -> ValidationResult: """Validate the body of a lawful basis attachment.""" result = ValidationResult(True) # Validate required fields required_fields = ["lawful_basis", "expiration", "purpose_grants"] for field in required_fields: if field not in body: result.add_error(f"Missing required field: {field}") # Validate lawful_basis if "lawful_basis" in body: lawful_basis = body["lawful_basis"] if not _member(lawful_basis, self.supported_lawful_bases): result.add_error(f"Unsupported lawful basis: {lawful_basis}") # Validate expiration if "expiration" in body: expiration = body["expiration"] if expiration is not None: exp_dt = _parse_timestamp(expiration) if exp_dt is None: result.add_error("Invalid expiration timestamp format") elif exp_dt <= datetime.now(timezone.utc): result.add_warning("Lawful basis has expired") # Validate purpose_grants if "purpose_grants" in body: purpose_grants = body["purpose_grants"] if not isinstance(purpose_grants, list): result.add_error("purpose_grants must be a list") else: for i, grant in enumerate(purpose_grants): grant_result = self._validate_purpose_grant(grant) if not grant_result.is_valid: result.add_error(f"Purpose grant {i}: {', '.join(grant_result.errors)}") result.is_valid = False result.warnings.extend([f"Grant {i}: {w}" for w in grant_result.warnings]) # Validate optional fields if "content_hash" in body: hash_result = self._validate_content_hash(body["content_hash"]) result.warnings.extend(f"Content hash: {w}" for w in hash_result.warnings) if not hash_result.is_valid: result.add_error(f"Content hash validation failed: {', '.join(hash_result.errors)}") result.is_valid = False if "proof_mechanisms" in body: proof_mechanisms = body["proof_mechanisms"] if not isinstance(proof_mechanisms, list): result.add_error("proof_mechanisms must be a list") else: for i, proof in enumerate(proof_mechanisms): proof_result = self._validate_proof_mechanism(proof) result.warnings.extend(f"Proof mechanism {i}: {w}" for w in proof_result.warnings) if not proof_result.is_valid: result.add_error(f"Proof mechanism {i}: {', '.join(proof_result.errors)}") result.is_valid = False if "registry" in body: registry_result = self._validate_registry_info(body["registry"]) if not registry_result.is_valid: result.add_error(f"Registry validation failed: {', '.join(registry_result.errors)}") result.is_valid = False return result def _validate_purpose_grant(self, grant: Dict[str, Any]) -> ValidationResult: """Validate a purpose grant.""" result = ValidationResult(True) grant = _fields(grant) required_fields = ["purpose", "granted", "granted_at"] for field in required_fields: if field not in grant: result.add_error(f"Missing required field in purpose grant: {field}") # Validate granted field if "granted" in grant and not isinstance(grant["granted"], bool): result.add_error("granted field must be a boolean") # Validate granted_at timestamp if "granted_at" in grant and _parse_timestamp(grant["granted_at"]) is None: result.add_error("Invalid granted_at timestamp format") # Validate conditions if "conditions" in grant: conditions = grant["conditions"] if not isinstance(conditions, list): result.add_error("conditions must be a list") elif not all(isinstance(c, str) for c in conditions): result.add_error("All conditions must be strings") return result def _validate_content_hash(self, content_hash: Dict[str, Any]) -> ValidationResult: """Validate content hash information.""" result = ValidationResult(True) content_hash = _fields(content_hash) required_fields = ["algorithm", "canonicalization", "value"] for field in required_fields: if field not in content_hash: result.add_error(f"Missing required field in content_hash: {field}") # Validate algorithm if "algorithm" in content_hash: algorithm = content_hash["algorithm"] if not _member(algorithm, self.supported_hash_algorithms): result.add_warning(f"Hash algorithm {algorithm!r} is not one this library can verify") # Validate canonicalization if "canonicalization" in content_hash: canonicalization = content_hash["canonicalization"] if not _member(canonicalization, self.supported_canonicalization): result.add_warning(f"Canonicalization method {canonicalization!r} is not one this library can apply") # Validate hash value format if "value" in content_hash: value = content_hash["value"] if not isinstance(value, str) or not all(c in '0123456789abcdefABCDEF' for c in value): result.add_error("Hash value must be a hexadecimal string") return result def _validate_proof_mechanism(self, proof: Dict[str, Any]) -> ValidationResult: """Validate a proof mechanism.""" result = ValidationResult(True) proof = _fields(proof) required_fields = ["proof_type", "timestamp", "proof_data"] for field in required_fields: if field not in proof: result.add_error(f"Missing required field in proof mechanism: {field}") # Validate proof_type if "proof_type" in proof: proof_type = proof["proof_type"] if not _member(proof_type, self.supported_proof_types): result.add_warning(f"Proof type {proof_type!r} is not one of the types the draft defines") # Validate timestamp if "timestamp" in proof and _parse_timestamp(proof["timestamp"]) is None: result.add_error("Invalid timestamp format in proof mechanism") # Validate proof_data if "proof_data" in proof: if not isinstance(proof["proof_data"], dict): result.add_error("proof_data must be a dictionary") return result def _validate_registry_info(self, registry: Dict[str, Any]) -> ValidationResult: """Validate registry information.""" result = ValidationResult(True) registry = _fields(registry) required_fields = ["type", "url"] for field in required_fields: if field not in registry: result.add_error(f"Missing required field in registry: {field}") # Validate registry type if "type" in registry: registry_type = registry["type"] if registry_type != "scitt": # Add more types as they're defined result.add_warning(f"Unknown registry type: {registry_type}") # Validate URL format (basic validation) if "url" in registry: url = registry["url"] if not isinstance(url, str) or not url.startswith(('http://', 'https://')): result.add_error("Registry URL must be a valid HTTP/HTTPS URL") return result
[docs] def validate_lawful_basis_attachment(self, attachment: LawfulBasisAttachment) -> ValidationResult: """Validate a LawfulBasisAttachment object.""" result = ValidationResult(True) # Check if expired if not attachment.is_valid(): result.add_error("Lawful basis has expired") # Validate content hash if present if attachment.content_hash and not attachment.validate_content_hash(): result.add_error("Content hash validation failed") # Validate purpose grants if not attachment.purpose_grants: result.add_error("At least one purpose grant is required") # Check for expired grants for grant in attachment.purpose_grants: if grant.is_expired(attachment.status_interval): result.add_warning(f"Purpose grant for '{grant.purpose}' has expired") return result