"""
Lawful Basis Attachment Classes
This module implements the core data structures for lawful basis attachments
as defined in the draft specification.
"""
from enum import Enum
from typing import List, Dict, Optional, Union, Any
from datetime import datetime, timezone
import hashlib
import json
import logging
logger = logging.getLogger(__name__)
[docs]class LawfulBasisType(Enum):
"""Types of lawful bases for processing personal data."""
CONSENT = "consent"
CONTRACT = "contract"
LEGAL_OBLIGATION = "legal_obligation"
VITAL_INTERESTS = "vital_interests"
PUBLIC_TASK = "public_task"
LEGITIMATE_INTERESTS = "legitimate_interests"
[docs]class ProofType(Enum):
"""Types of proof mechanisms for lawful basis."""
VERBAL_CONFIRMATION = "verbal_confirmation"
SIGNED_DOCUMENT = "signed_document"
CRYPTOGRAPHIC_SIGNATURE = "cryptographic_signature"
EXTERNAL_SYSTEM = "external_system"
[docs]class HashAlgorithm(Enum):
"""Supported hash algorithms for content integrity."""
SHA_256 = "sha-256"
SHA_3_256 = "sha-3-256"
BLAKE2B_256 = "blake2b-256"
[docs]class CanonicalizationMethod(Enum):
"""Supported canonicalization methods."""
JCS = "jcs" # JSON Canonicalization Scheme
[docs]class PurposeGrant:
"""Represents a purpose-specific permission grant."""
def __init__(
self,
purpose: str,
granted: bool,
granted_at: Union[str, datetime],
conditions: Optional[List[str]] = None
):
self.purpose = purpose
self.granted = granted
self.granted_at = self._normalize_timestamp(granted_at)
self.conditions = conditions or []
def _normalize_timestamp(self, timestamp: Union[str, datetime]) -> datetime:
"""Normalize timestamp to datetime object."""
if isinstance(timestamp, str):
return datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
return timestamp
[docs] def is_expired(self, status_interval: Optional[str] = None) -> bool:
"""Check if the grant has expired based on status interval."""
if not status_interval:
return False
# Parse status interval (e.g., "30d", "1y")
# This is a simplified implementation
# In practice, you'd want more robust interval parsing
try:
if status_interval.endswith('d'):
days = int(status_interval[:-1])
expiry = self.granted_at + datetime.timedelta(days=days)
return datetime.now(timezone.utc) > expiry
elif status_interval.endswith('y'):
years = int(status_interval[:-1])
expiry = self.granted_at.replace(year=self.granted_at.year + years)
return datetime.now(timezone.utc) > expiry
except (ValueError, AttributeError):
logger.warning(f"Invalid status interval format: {status_interval}")
return False
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
result = {
"purpose": self.purpose,
"granted": self.granted,
"granted_at": self.granted_at.isoformat()
}
if self.conditions:
result["conditions"] = self.conditions
return result
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'PurposeGrant':
"""Create from dictionary representation."""
return cls(
purpose=data["purpose"],
granted=data["granted"],
granted_at=data["granted_at"],
conditions=data.get("conditions")
)
[docs]class ContentHash:
"""Represents content integrity information."""
def __init__(
self,
algorithm: Union[HashAlgorithm, str],
canonicalization: Union[CanonicalizationMethod, str],
value: str
):
# Accept the enum or its string value ("sha-256", "jcs"); a value
# outside the enum raises ValueError here rather than later in to_dict().
self.algorithm = HashAlgorithm(algorithm.lower() if isinstance(algorithm, str) else algorithm)
self.canonicalization = CanonicalizationMethod(
canonicalization.lower() if isinstance(canonicalization, str) else canonicalization
)
self.value = value
[docs] def validate(self, content: Dict[str, Any]) -> bool:
"""Validate content against the hash."""
try:
canonical_content = self._canonicalize(content)
computed_hash = self._compute_hash(canonical_content)
return computed_hash == self.value
except Exception as e:
logger.error(f"Content hash validation failed: {str(e)}")
return False
def _canonicalize(self, content: Dict[str, Any]) -> str:
"""Apply canonicalization method."""
if self.canonicalization == CanonicalizationMethod.JCS:
# Implement JSON Canonicalization Scheme (RFC 8785)
# This is a simplified implementation
return json.dumps(content, sort_keys=True, separators=(',', ':'))
else:
raise ValueError(f"Unsupported canonicalization: {self.canonicalization}")
def _compute_hash(self, content: str) -> str:
"""Compute hash using specified algorithm."""
content_bytes = content.encode('utf-8')
if self.algorithm == HashAlgorithm.SHA_256:
return hashlib.sha256(content_bytes).hexdigest()
elif self.algorithm == HashAlgorithm.SHA_3_256:
return hashlib.sha3_256(content_bytes).hexdigest()
elif self.algorithm == HashAlgorithm.BLAKE2B_256:
return hashlib.blake2b(content_bytes, digest_size=32).hexdigest()
else:
raise ValueError(f"Unsupported hash algorithm: {self.algorithm}")
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
return {
"algorithm": self.algorithm.value,
"canonicalization": self.canonicalization.value,
"value": self.value
}
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'ContentHash':
"""Create from dictionary representation."""
return cls(
algorithm=HashAlgorithm(data["algorithm"]),
canonicalization=CanonicalizationMethod(data["canonicalization"]),
value=data["value"]
)
[docs]class ProofMechanism:
"""Represents a proof mechanism for lawful basis."""
def __init__(
self,
proof_type: ProofType,
timestamp: Union[str, datetime],
proof_data: Dict[str, Any]
):
self.proof_type = proof_type
self.timestamp = self._normalize_timestamp(timestamp)
self.proof_data = proof_data
def _normalize_timestamp(self, timestamp: Union[str, datetime]) -> datetime:
"""Normalize timestamp to datetime object."""
if isinstance(timestamp, str):
return datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
return timestamp
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
return {
"proof_type": self.proof_type.value,
"timestamp": self.timestamp.isoformat(),
"proof_data": self.proof_data
}
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'ProofMechanism':
"""Create from dictionary representation."""
return cls(
proof_type=ProofType(data["proof_type"]),
timestamp=data["timestamp"],
proof_data=data["proof_data"]
)
[docs]class RegistryInfo:
"""Represents external attestation registry information."""
def __init__(self, registry_type: str, url: str):
self.registry_type = registry_type
self.url = url
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
return {
"type": self.registry_type,
"url": self.url
}
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'RegistryInfo':
"""Create from dictionary representation."""
return cls(
registry_type=data["type"],
url=data["url"]
)
[docs]class LawfulBasisAttachment:
"""
Represents a lawful basis attachment for vCon processing.
This class handles the creation, validation, and processing of lawful
basis attachments according to the draft specification.
"""
def __init__(
self,
lawful_basis: LawfulBasisType,
expiration: Optional[Union[str, datetime]],
purpose_grants: List[PurposeGrant],
terms_of_service: Optional[str] = None,
status_interval: Optional[str] = None,
content_hash: Optional[ContentHash] = None,
registry: Optional[RegistryInfo] = None,
proof_mechanisms: Optional[List[ProofMechanism]] = None,
metadata: Optional[Dict[str, Any]] = None
):
self.lawful_basis = lawful_basis
self.expiration = self._normalize_timestamp(expiration) if expiration else None
self.purpose_grants = purpose_grants
self.terms_of_service = terms_of_service
self.status_interval = status_interval
self.content_hash = content_hash
self.registry = registry
self.proof_mechanisms = proof_mechanisms or []
self.metadata = metadata or {}
def _normalize_timestamp(self, timestamp: Union[str, datetime]) -> datetime:
"""Normalize timestamp to datetime object."""
if isinstance(timestamp, str):
return datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
return timestamp
[docs] def is_valid(self) -> bool:
"""Check if the lawful basis is currently valid."""
if self.expiration is None:
return True
now = datetime.now(timezone.utc)
return now < self.expiration
[docs] def has_permission(self, purpose: str) -> bool:
"""Check if permission is granted for a specific purpose."""
for grant in self.purpose_grants:
if grant.purpose == purpose:
return grant.granted
return False
[docs] def get_conditions(self, purpose: str) -> List[str]:
"""Get conditions for a specific purpose grant."""
for grant in self.purpose_grants:
if grant.purpose == purpose:
return grant.conditions or []
return []
[docs] def validate_content_hash(self) -> bool:
"""Validate the content hash if present."""
if not self.content_hash:
return True
return self.content_hash.validate(self.to_dict())
[docs] def to_dict(self) -> Dict[str, Any]:
"""Convert to dictionary representation."""
result = {
"lawful_basis": self.lawful_basis.value,
"expiration": self.expiration.isoformat() if self.expiration else None,
"purpose_grants": [grant.to_dict() for grant in self.purpose_grants]
}
if self.terms_of_service:
result["terms_of_service"] = self.terms_of_service
if self.status_interval:
result["status_interval"] = self.status_interval
if self.content_hash:
result["content_hash"] = self.content_hash.to_dict()
if self.registry:
result["registry"] = self.registry.to_dict()
if self.proof_mechanisms:
result["proof_mechanisms"] = [proof.to_dict() for proof in self.proof_mechanisms]
if self.metadata:
result["metadata"] = self.metadata
return result
[docs] @classmethod
def from_dict(cls, data: Dict[str, Any]) -> 'LawfulBasisAttachment':
"""Create from dictionary representation."""
return cls(
lawful_basis=LawfulBasisType(data["lawful_basis"]),
expiration=data.get("expiration"),
purpose_grants=[PurposeGrant.from_dict(g) for g in data["purpose_grants"]],
terms_of_service=data.get("terms_of_service"),
status_interval=data.get("status_interval"),
content_hash=ContentHash.from_dict(data["content_hash"]) if data.get("content_hash") else None,
registry=RegistryInfo.from_dict(data["registry"]) if data.get("registry") else None,
proof_mechanisms=[ProofMechanism.from_dict(p) for p in data.get("proof_mechanisms", [])],
metadata=data.get("metadata")
)