krons 0.1.0__py3-none-any.whl

kronos/enforcement/common/model.py

@@ -0,0 +1,102 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..rule import Rule, RuleParams, RuleQualifier
+
+__all__ = ("BaseModelRule",)
+
+
+def _get_basemodel_params() -> RuleParams:
+    """Default params: applies to BaseModel via ANNOTATION qualifier, auto_fix enabled."""
+    return RuleParams(
+        apply_types={BaseModel},
+        apply_fields=set(),
+        default_qualifier=RuleQualifier.ANNOTATION,
+        auto_fix=True,
+        kw={},
+    )
+
+
+class BaseModelRule(Rule):
+    """Rule for validating Pydantic BaseModel subclasses.
+
+    Validates values against expected Pydantic model types with auto-conversion from dict.
+    Uses model_validate() for dict-to-model conversion when auto_fix is enabled.
+
+    Usage:
+        rule = BaseModelRule()
+        result = await rule.invoke("config", {"name": "test"}, MyModel)  # -> MyModel instance
+    """
+
+    def __init__(
+        self,
+        params: RuleParams | None = None,
+        **kw,
+    ):
+        """Initialize BaseModel rule.
+
+        Args:
+            params: Custom RuleParams (uses default if None)
+            **kw: Additional validation kwargs
+        """
+        if params is None:
+            params = _get_basemodel_params()
+        super().__init__(params, **kw)
+
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate value as a Pydantic model.
+
+        Args:
+            v: Value to validate
+            t: Expected BaseModel subclass
+
+        Raises:
+            ValueError: If value cannot be validated as the model type
+        """
+        if not isinstance(t, type) or not issubclass(t, BaseModel):
+            raise ValueError(f"expected_type must be a BaseModel subclass, got {t}")
+
+        if isinstance(v, t):
+            return
+
+        if isinstance(v, dict):
+            try:
+                t.model_validate(v)
+                return
+            except Exception as e:
+                raise ValueError(f"Dict validation failed: {e}") from e
+
+        raise ValueError(f"Cannot validate {type(v).__name__} as {t.__name__}")
+
+    async def perform_fix(self, v: Any, t: type) -> Any:
+        """Attempt to convert value to model using standard validation.
+
+        Args:
+            v: Value to fix
+            t: Expected BaseModel subclass
+
+        Returns:
+            Validated model instance
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        if not isinstance(t, type) or not issubclass(t, BaseModel):
+            raise ValueError(f"expected_type must be a BaseModel subclass, got {t}")
+
+        if isinstance(v, t):
+            return v
+
+        if isinstance(v, dict):
+            try:
+                return t.model_validate(v)
+            except Exception as e:
+                raise ValueError(f"Cannot convert dict to {t.__name__}: {e}") from e
+
+        raise ValueError(f"Cannot convert {type(v).__name__} to {t.__name__}")

kronos/enforcement/common/number.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from ..rule import Rule, RuleParams, RuleQualifier
+
+__all__ = ("NumberRule",)
+
+
+def _get_number_params() -> RuleParams:
+    """Default params: applies to int/float via ANNOTATION qualifier, auto_fix enabled."""
+    return RuleParams(
+        apply_types={int, float},
+        apply_fields=set(),
+        default_qualifier=RuleQualifier.ANNOTATION,
+        auto_fix=True,
+        kw={},
+    )
+
+
+class NumberRule(Rule):
+    """Rule for validating and converting numeric values.
+
+    Features:
+    - Type checking (int or float)
+    - Range constraints (ge, gt, le, lt)
+    - Auto-conversion from string/other types to number
+
+    Usage:
+        rule = NumberRule(ge=0.0, le=1.0)  # Confidence score
+        result = await rule.invoke("confidence", 0.95, float)
+    """
+
+    def __init__(
+        self,
+        ge: int | float | None = None,
+        gt: int | float | None = None,
+        le: int | float | None = None,
+        lt: int | float | None = None,
+        params: RuleParams | None = None,
+        **kw,
+    ):
+        """Initialize number rule.
+
+        Args:
+            ge: Greater than or equal to (>=)
+            gt: Greater than (>)
+            le: Less than or equal to (<=)
+            lt: Less than (<)
+            params: Custom RuleParams (uses default if None)
+            **kw: Additional validation kwargs
+        """
+        if params is None:
+            params = _get_number_params()
+        super().__init__(params, **kw)
+        self.ge = ge
+        self.gt = gt
+        self.le = le
+        self.lt = lt
+
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate that value is a number within constraints.
+
+        Raises:
+            ValueError: If not a number or constraints violated
+        """
+        if not isinstance(v, (int, float)):
+            raise ValueError(f"Invalid number value: expected int or float, got {type(v).__name__}")
+
+        if self.ge is not None and v < self.ge:
+            raise ValueError(f"Number too small: {v} < {self.ge}")
+        if self.gt is not None and v <= self.gt:
+            raise ValueError(f"Number too small: {v} <= {self.gt}")
+        if self.le is not None and v > self.le:
+            raise ValueError(f"Number too large: {v} > {self.le}")
+        if self.lt is not None and v >= self.lt:
+            raise ValueError(f"Number too large: {v} >= {self.lt}")
+
+    async def perform_fix(self, v: Any, t: type) -> Any:
+        """Attempt to convert value to number and re-validate.
+
+        Returns:
+            Numeric value (int or float), validated against constraints
+
+        Raises:
+            ValueError: If conversion or re-validation fails
+        """
+        fixed: int | float
+        try:
+            if isinstance(v, str):
+                v = v.strip()
+            fixed = int(v) if t is int else float(v)
+        except (ValueError, TypeError) as e:
+            raise ValueError(f"Failed to convert {v} to number") from e
+
+        await self.validate(fixed, t)
+        return fixed

kronos/enforcement/common/string.py

@@ -0,0 +1,140 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from re import Pattern
+from typing import Any
+
+from ..rule import Rule, RuleParams, RuleQualifier
+
+__all__ = ("StringRule",)
+
+# ReDoS protection: max input length for regex matching
+DEFAULT_REGEX_MAX_INPUT_LENGTH = 10_000
+
+# Heuristic ReDoS detection (nested quantifiers). Not exhaustive - for untrusted
+# patterns use google-re2 or regex timeout. Input length limit provides additional mitigation.
+_REDOS_PATTERNS = [
+    r"\(\.\*\)\*",
+    r"\(\.\+\)\*",
+    r"\(\.\*\)\+",
+    r"\(\.\+\)\+",
+    r"\(\[.*?\]\+\)\+",
+    r"\(\[.*?\]\*\)\*",
+]
+_REDOS_DETECTOR = re.compile("|".join(_REDOS_PATTERNS))
+
+
+def _get_string_params() -> RuleParams:
+    """Default params: applies to str via ANNOTATION qualifier, auto_fix enabled."""
+    return RuleParams(
+        apply_types={str},
+        apply_fields=set(),
+        default_qualifier=RuleQualifier.ANNOTATION,
+        auto_fix=True,
+        kw={},
+    )
+
+
+class StringRule(Rule):
+    """Rule for validating and converting string values.
+
+    Features:
+    - Type checking (must be str)
+    - Length constraints (min_length, max_length)
+    - Pattern matching (regex) with ReDoS protection
+    - Auto-conversion from any type to string
+
+    Usage:
+        rule = StringRule(min_length=1, max_length=100, pattern=r'^[A-Za-z]+$')
+        result = await rule.invoke("name", "Ocean", str)
+    """
+
+    def __init__(
+        self,
+        min_length: int | None = None,
+        max_length: int | None = None,
+        pattern: str | None = None,
+        regex_max_input_length: int = DEFAULT_REGEX_MAX_INPUT_LENGTH,
+        params: RuleParams | None = None,
+        **kw,
+    ):
+        """Initialize string rule.
+
+        Args:
+            min_length: Minimum string length (inclusive)
+            max_length: Maximum string length (inclusive)
+            pattern: Regex pattern to match. Patterns with nested quantifiers
+                are rejected to prevent ReDoS attacks.
+            regex_max_input_length: Maximum input length for regex matching
+                (default 10,000 chars). Inputs exceeding this are rejected.
+            params: Custom RuleParams (uses default if None)
+            **kw: Additional validation kwargs
+
+        Raises:
+            ValueError: If pattern contains potential ReDoS vulnerabilities
+        """
+        if params is None:
+            params = _get_string_params()
+        super().__init__(params, **kw)
+        self.min_length = min_length
+        self.max_length = max_length
+        self.regex_max_input_length = regex_max_input_length
+
+        self._compiled_pattern: Pattern[str] | None
+        if pattern is not None:
+            if _REDOS_DETECTOR.search(pattern):
+                raise ValueError(
+                    f"Pattern '{pattern}' contains nested quantifiers that could cause "
+                    "ReDoS (Regular Expression Denial of Service). Use simpler patterns."
+                )
+            try:
+                self._compiled_pattern = re.compile(pattern)
+            except re.error as e:
+                raise ValueError(f"Invalid regex pattern '{pattern}': {e}") from e
+        else:
+            self._compiled_pattern = None
+        self.pattern = pattern
+
+    async def validate(self, v: Any, t: type, **kw) -> None:
+        """Validate that value is a string with correct length and pattern.
+
+        Raises:
+            ValueError: If not a string or constraints violated
+        """
+        if not isinstance(v, str):
+            raise ValueError(f"Invalid string value: expected str, got {type(v).__name__}")
+
+        if self.min_length is not None and len(v) < self.min_length:
+            raise ValueError(
+                f"String too short: got {len(v)} characters, minimum {self.min_length}"
+            )
+        if self.max_length is not None and len(v) > self.max_length:
+            raise ValueError(f"String too long: got {len(v)} characters, maximum {self.max_length}")
+
+        if self._compiled_pattern is not None:
+            if len(v) > self.regex_max_input_length:
+                raise ValueError(
+                    f"String too long for regex matching: got {len(v)} characters, "
+                    f"maximum {self.regex_max_input_length}"
+                )
+            if not self._compiled_pattern.match(v):
+                raise ValueError(f"String does not match required pattern: {self.pattern}")
+
+    async def perform_fix(self, v: Any, t: type) -> Any:
+        """Attempt to convert value to string and re-validate.
+
+        Returns:
+            String representation of value (validated)
+
+        Raises:
+            ValueError: If conversion or re-validation fails
+        """
+        try:
+            fixed = str(v)
+        except Exception as e:
+            raise ValueError(f"Failed to convert {v} to string") from e
+
+        # Re-validate the fixed value
+        await self.validate(fixed, t)
+        return fixed

kronos/enforcement/context.py

@@ -0,0 +1,129 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Request context for service operations."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Protocol
+from uuid import UUID, uuid4
+
+from kronos.types.base import DataClass
+from kronos.types.identity import ID
+
+if TYPE_CHECKING:
+    from kronos.session import Branch, Session
+
+__all__ = ("QueryFn", "RequestContext")
+
+
+class QueryFn(Protocol):
+    """Protocol for CRUD query functions used by declarative phrases.
+
+    The query_fn is the bridge between declarative CrudPattern phrases
+    and the actual database backend. Implementations MUST use parameterized
+    queries to prevent SQL injection.
+
+    Args:
+        table: Validated database table name (alphanumeric + underscores only).
+        operation: CRUD operation enum value.
+        where: WHERE clause as dict of column -> value. None for insert.
+        data: Data dict for insert/update. None for select/delete.
+        ctx: The RequestContext (for connection, tenant isolation, etc).
+
+    Returns:
+        Row as dict if found/affected, None otherwise.
+    """
+
+    def __call__(
+        self,
+        table: str,
+        operation: str,
+        where: dict[str, Any] | None,
+        data: dict[str, Any] | None,
+        ctx: RequestContext,
+    ) -> Awaitable[dict[str, Any] | None]: ...
+
+
+@dataclass(slots=True)
+class RequestContext(DataClass):
+    """Context for a service request.
+
+    Carries identity, scope, and metadata through the call chain.
+    Extra kwargs become metadata entries accessible as attributes.
+
+    Core fields (slots):
+        name, id, session_id, branch_id, conn, query_fn, now
+
+    Extension fields (metadata, accessible via attribute access):
+        Any kwarg passed to __init__ is stored in metadata and accessible
+        as ctx.field_name. Common extensions:
+        - tenant_id: Tenant scope (auto-added to WHERE clauses)
+        - actor_id: Who is performing the action
+        - subject_id: Person subject of the operation
+        - correlation_id: Trace ID linking related operations
+        - causation_id: Parent operation that caused this
+        - charter: Active governance document
+        - jurisdictions: Jurisdiction scope tuple
+
+    Usage:
+        ctx = RequestContext(
+            name="consent.grant",
+            conn=connection,
+            tenant_id=tenant_uuid,
+            actor_id=actor_uuid,
+            subject_id=subject_uuid,
+            correlation_id=trace_id,
+        )
+        ctx.tenant_id   # -> tenant_uuid (from metadata)
+        ctx.subject_id   # -> subject_uuid (from metadata)
+    """
+
+    name: str
+    id: UUID = field(default_factory=uuid4)
+    session_id: ID[Session] | None = None
+    branch_id: ID[Branch] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    conn: Any | None = None
+    query_fn: QueryFn | None = None
+    now: datetime | None = None
+
+    def __init__(
+        self,
+        name: str,
+        session_id: ID[Session] | None = None,
+        branch_id: ID[Branch] | None = None,
+        id: UUID | None = None,
+        conn: Any | None = None,
+        query_fn: QueryFn | None = None,
+        now: datetime | None = None,
+        **kwargs: Any,
+    ):
+        self.name = name
+        self.id = id or uuid4()
+        self.session_id = session_id
+        self.branch_id = branch_id
+        self.conn = conn
+        self.query_fn = query_fn
+        self.now = now
+        self.metadata = kwargs
+
+    def __getattr__(self, name: str) -> Any:
+        """Look up unknown attributes in metadata.
+
+        Called only when normal attribute lookup fails (slots miss).
+        Raises AttributeError for keys not present in metadata so that
+        hasattr() works correctly.
+        """
+        if name.startswith("_"):
+            raise AttributeError(name)
+        metadata = object.__getattribute__(self, "metadata")
+        try:
+            return metadata[name]
+        except KeyError:
+            raise AttributeError(
+                f"'{type(self).__name__}' has no attribute '{name}'"
+            ) from None

kronos/enforcement/policy.py

@@ -0,0 +1,80 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Policy protocols and types.
+
+Defines contracts for policy resolution and evaluation.
+Implementations provided by domain libs (e.g., canon-core).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from kronos.enforcement.context import RequestContext
+from kronos.specs.catalog._enforcement import EnforcementLevel
+from kronos.types.base import DataClass
+
+__all__ = (
+    "EnforcementLevel",
+    "PolicyEngine",
+    "PolicyResolver",
+    "ResolvedPolicy",
+)
+
+
+@dataclass(slots=True)
+class ResolvedPolicy(DataClass):
+    """A policy resolved for evaluation.
+
+    Returned by PolicyResolver.resolve(). Contains policy ID and
+    any resolution metadata needed by the engine.
+    """
+
+    policy_id: str
+    enforcement: str = EnforcementLevel.HARD_MANDATORY.value
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class PolicyEngine(Protocol):
+    """Abstract policy evaluation engine.
+
+    kron defines the contract. Implementations:
+    - canon-core: OPAEngine (Rego/Regorus evaluation)
+    - Testing: MockPolicyEngine
+    """
+
+    async def evaluate(
+        self,
+        policy_id: str,
+        input_data: dict[str, Any],
+        **options: Any,
+    ) -> Any:
+        """Evaluate a single policy against input."""
+        ...
+
+    async def evaluate_batch(
+        self,
+        policy_ids: Sequence[str],
+        input_data: dict[str, Any],
+        **options: Any,
+    ) -> list[Any]:
+        """Evaluate multiple policies."""
+        ...
+
+
+@runtime_checkable
+class PolicyResolver(Protocol):
+    """Resolves which policies apply to a given context.
+
+    kron defines the contract. Implementations:
+    - canon-core: CharteredResolver (charter-based resolution)
+    - Testing: MockPolicyResolver, StaticPolicyResolver
+    """
+
+    def resolve(self, ctx: RequestContext) -> Sequence[ResolvedPolicy]:
+        """Determine applicable policies for context."""
+        ...

kronos/enforcement/registry.py

@@ -0,0 +1,153 @@
+# Copyright (c) 2025 - 2026, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .rule import Rule
+
+__all__ = ("RuleRegistry", "get_default_registry")
+
+_default_registry: RuleRegistry | None = None
+
+
+class RuleRegistry:
+    """Registry mapping types to Rule classes/instances.
+
+    Provides automatic Rule assignment based on Spec.base_type.
+    Supports inheritance-based lookup (subclasses inherit parent rules).
+
+    Usage:
+        registry = RuleRegistry()
+        registry.register(str, StringRule(min_length=1))
+        registry.register(int, NumberRule(ge=0))
+
+        rule = registry.get_rule(str)  # Returns StringRule instance
+        rule = registry.get_rule(MyStr)  # Returns StringRule (inherited)
+    """
+
+    def __init__(self):
+        """Initialize empty registry."""
+        self._type_rules: dict[type, Rule] = {}
+        self._name_rules: dict[str, Rule] = {}
+
+    def register(
+        self,
+        key: type | str,
+        rule: Rule,
+        *,
+        replace: bool = False,
+    ) -> None:
+        """Register a Rule for a type or field name.
+
+        Args:
+            key: Type or field name to register
+            rule: Rule instance to use
+            replace: Allow replacing existing registration
+
+        Raises:
+            ValueError: If key already registered and replace=False
+        """
+        if isinstance(key, str):
+            if key in self._name_rules and not replace:
+                raise ValueError(f"Rule already registered for field '{key}'")
+            self._name_rules[key] = rule
+        else:
+            if key in self._type_rules and not replace:
+                raise ValueError(f"Rule already registered for type {key}")
+            self._type_rules[key] = rule
+
+    def get_rule(
+        self,
+        base_type: type | None = None,
+        field_name: str | None = None,
+    ) -> Rule | None:
+        """Get Rule for a type or field name.
+
+        Priority:
+        1. Exact field name match
+        2. Exact type match
+        3. Inheritance-based type match (check base classes)
+
+        Args:
+            base_type: Type to look up
+            field_name: Field name to look up
+
+        Returns:
+            Rule instance or None if not found
+        """
+        if field_name and field_name in self._name_rules:
+            return self._name_rules[field_name]
+
+        if base_type and base_type in self._type_rules:
+            return self._type_rules[base_type]
+
+        if base_type:
+            for registered_type, rule in self._type_rules.items():
+                try:
+                    if issubclass(base_type, registered_type):
+                        return rule
+                except TypeError:
+                    continue
+
+        return None
+
+    def has_rule(self, key: type | str) -> bool:
+        """Check if a rule is registered for type or name."""
+        if isinstance(key, str):
+            return key in self._name_rules
+        return key in self._type_rules or any(
+            issubclass(key, t) for t in self._type_rules if isinstance(key, type)
+        )
+
+    def list_types(self) -> list[type]:
+        """List all registered types."""
+        return list(self._type_rules.keys())
+
+    def list_names(self) -> list[str]:
+        """List all registered field names."""
+        return list(self._name_rules.keys())
+
+
+def get_default_registry() -> RuleRegistry:
+    """Get the default rule registry with standard rules.
+
+    Standard mappings:
+        str -> StringRule
+        int -> NumberRule
+        float -> NumberRule
+        bool -> BooleanRule
+        dict -> MappingRule
+        BaseModel -> BaseModelRule (catches all Pydantic models)
+
+    Returns:
+        RuleRegistry with default rules registered
+    """
+    global _default_registry
+
+    if _default_registry is None:
+        from pydantic import BaseModel
+
+        from .common.boolean import BooleanRule
+        from .common.mapping import MappingRule
+        from .common.model import BaseModelRule
+        from .common.number import NumberRule
+        from .common.string import StringRule
+
+        _default_registry = RuleRegistry()
+        _default_registry.register(str, StringRule())
+        _default_registry.register(int, NumberRule())
+        _default_registry.register(float, NumberRule())
+        _default_registry.register(bool, BooleanRule())
+        _default_registry.register(dict, MappingRule())
+        _default_registry.register(BaseModel, BaseModelRule())
+
+    return _default_registry
+
+
+def reset_default_registry() -> None:
+    """Reset the default registry (for testing)."""
+    global _default_registry
+    _default_registry = None