contextwall 0.1.0__py3-none-any.whl

context_firewall/compliance/control_mappings.py

@@ -0,0 +1,92 @@
+"""Control mapping definitions for HIPAA, SOC2 Type II, and FedRAMP Moderate.
+
+Task 8.7: walk active policy rules, map to framework controls, set satisfied flag.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ControlRef:
+    framework: str
+    control_id: str
+    description: str
+
+
+# Built-in control mappings per rule name prefix / action type
+RULE_CONTROL_MAP: dict[str, list[ControlRef]] = {
+    # HIPAA minimum-necessary rule
+    "hipaa-minimum-necessary": [
+        ControlRef("hipaa", "45 CFR 164.502(b)", "Minimum Necessary Standard"),
+        ControlRef("hipaa", "45 CFR 164.514(d)", "Minimum Necessary - workforce access"),
+    ],
+    # HIPAA audit control
+    "hipaa-audit-control": [
+        ControlRef("hipaa", "45 CFR 164.312(b)", "Audit Controls"),
+    ],
+    # Untrusted source sanitization
+    "untrusted-source-sanitization": [
+        ControlRef("soc2", "CC6.1", "Logical and Physical Access Controls"),
+        ControlRef("soc2", "CC6.6", "External Threats - logical access controls"),
+        ControlRef("fedramp", "SI-3", "Malicious Code Protection"),
+    ],
+    # Secret detection
+    "block_secrets": [
+        ControlRef("soc2", "CC6.1", "Logical and Physical Access Controls"),
+        ControlRef("fedramp", "AC-3", "Access Enforcement"),
+    ],
+    # PII redaction
+    "redact_pii": [
+        ControlRef("hipaa", "45 CFR 164.502(b)", "Minimum Necessary Standard"),
+        ControlRef("gdpr", "Art. 5(1)(c)", "Data Minimisation"),
+    ],
+    # SOC2 logging
+    "soc2-policy-action-logging": [
+        ControlRef("soc2", "CC7.2", "System Monitoring"),
+        ControlRef("soc2", "CC8.1", "Change Management"),
+        ControlRef("fedramp", "AU-2", "Audit Events"),
+        ControlRef("fedramp", "AU-9", "Protection of Audit Information"),
+    ],
+}
+
+
+@dataclass
+class ControlMapping:
+    framework: str
+    control_id: str
+    description: str
+    satisfied: bool
+    rule_name: str
+
+
+def resolve_control_mappings(
+    fired_rule_names: set[str],
+    requested_framework: str | None = None,
+) -> list[ControlMapping]:
+    """Map fired rules to compliance controls.
+
+    satisfied=True when the rule fired in the session (evidence exists).
+    satisfied=False when the control is required but the rule did not fire.
+    """
+    mappings: list[ControlMapping] = []
+    seen: set[tuple[str, str]] = set()
+
+    for rule_name, refs in RULE_CONTROL_MAP.items():
+        for ref in refs:
+            if requested_framework and ref.framework != requested_framework:
+                continue
+            key = (ref.framework, ref.control_id)
+            if key in seen:
+                continue
+            seen.add(key)
+            mappings.append(ControlMapping(
+                framework=ref.framework,
+                control_id=ref.control_id,
+                description=ref.description,
+                satisfied=rule_name in fired_rule_names,
+                rule_name=rule_name,
+            ))
+
+    return mappings

context_firewall/compliance/export.py

@@ -0,0 +1,280 @@
+"""Compliance export bundle assembler.
+
+Generates signed, Merkle-chained ComplianceExportBundle sliced by session ID,
+time range, or framework filter.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+from context_firewall.compliance.chain import (
+    CHAIN_GENESIS_HASH,
+    ChainEntry,
+    compute_entry_hash,
+    verify_chain,
+)
+from context_firewall.compliance.control_mappings import (
+    ControlMapping,
+    resolve_control_mappings,
+)
+from context_firewall.compliance.keys import load_public_key_pem, sign_bundle
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ChainProof:
+    first_sequence: int
+    last_sequence: int
+    entry_count: int
+    first_hash: str
+    last_hash: str
+    hmac_algorithm: str = "HMAC-SHA256"
+    chain_valid: bool = True
+    chain_error: str = ""
+
+
+@dataclass
+class TenantMetadata:
+    tenant_id: str = ""
+    deployment_mode: str = "self-hosted"
+    baa_mode: bool = False
+    export_generated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    cre_version: str = "0.1.0"
+
+
+@dataclass
+class RetentionPolicy:
+    retention_days: int = 365
+    baa_override_applied: bool = False
+    framework: str = ""
+
+
+@dataclass
+class ComplianceExportBundle:
+    bundle_id: str
+    export_scope: dict[str, Any]
+    provenance_entries: list[dict[str, Any]]
+    chain_proof: ChainProof
+    control_mappings: list[dict[str, Any]]
+    tenant_metadata: TenantMetadata
+    retention_policy: RetentionPolicy
+    public_key_pem: str = ""
+    signature: str = ""
+
+    def canonical_json(self) -> bytes:
+        """Deterministic JSON for signing - excludes signature field."""
+        doc = {
+            "bundle_id": self.bundle_id,
+            "export_scope": self.export_scope,
+            "chain_proof": asdict(self.chain_proof),
+            "control_mappings": self.control_mappings,
+            "tenant_metadata": asdict(self.tenant_metadata),
+            "retention_policy": asdict(self.retention_policy),
+            "entry_count": len(self.provenance_entries),
+        }
+        return json.dumps(doc, sort_keys=True, separators=(",", ":")).encode()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "bundle_id": self.bundle_id,
+            "export_scope": self.export_scope,
+            "provenance_entries": self.provenance_entries,
+            "chain_proof": asdict(self.chain_proof),
+            "control_mappings": self.control_mappings,
+            "tenant_metadata": asdict(self.tenant_metadata),
+            "retention_policy": asdict(self.retention_policy),
+            "public_key_pem": self.public_key_pem,
+            "signature": self.signature,
+        }
+
+
+@dataclass
+class ExportScope:
+    session_id: str | None = None
+    from_ts: str | None = None
+    to_ts: str | None = None
+    framework: str | None = None
+
+
+class ComplianceExporter:
+    def __init__(
+        self,
+        db_path: str,
+        hmac_key: str,
+        baa_mode: bool = False,
+        key_dir: Path | None = None,
+        tenant_id: str = "",
+    ) -> None:
+        self._db_path = db_path
+        self._hmac_key = hmac_key
+        self._baa_mode = baa_mode
+        self._key_dir = key_dir or Path(".ctxfw/keys")
+        self._tenant_id = tenant_id
+
+    async def export(self, scope: ExportScope) -> ComplianceExportBundle:
+        """Build and sign a ComplianceExportBundle for the given scope."""
+        entries = await self._fetch_entries(scope)
+        chain_entries = self._to_chain_entries(entries)
+        chain_proof = self._build_chain_proof(chain_entries)
+
+        fired_rules = self._collect_fired_rules(entries)
+        control_mappings = resolve_control_mappings(fired_rules, scope.framework)
+
+        bundle_id = str(uuid.uuid4())
+        retention = self._build_retention_policy(scope.framework)
+        tenant_meta = TenantMetadata(
+            tenant_id=self._tenant_id,
+            baa_mode=self._baa_mode,
+        )
+
+        bundle = ComplianceExportBundle(
+            bundle_id=bundle_id,
+            export_scope={
+                "session_id": scope.session_id,
+                "from_ts": scope.from_ts,
+                "to_ts": scope.to_ts,
+                "framework": scope.framework,
+            },
+            provenance_entries=entries,
+            chain_proof=chain_proof,
+            control_mappings=[
+                {
+                    "framework": cm.framework,
+                    "control_id": cm.control_id,
+                    "description": cm.description,
+                    "satisfied": cm.satisfied,
+                    "rule_name": cm.rule_name,
+                }
+                for cm in control_mappings
+            ],
+            tenant_metadata=tenant_meta,
+            retention_policy=retention,
+            public_key_pem=load_public_key_pem(self._key_dir) or "",
+        )
+
+        sig = sign_bundle(bundle.canonical_json(), self._key_dir)
+        bundle.signature = sig or ""
+
+        return bundle
+
+    async def verify(self, bundle: ComplianceExportBundle) -> tuple[bool, str]:
+        """Verify chain integrity and signature of a bundle."""
+        chain_entries = self._to_chain_entries(bundle.provenance_entries)
+        chain_ok, chain_err = verify_chain(chain_entries, self._hmac_key)
+        if not chain_ok:
+            return False, f"chain-integrity-violation: {chain_err}"
+
+        if bundle.signature and bundle.public_key_pem:
+            from context_firewall.compliance.keys import verify_signature
+            sig_ok = verify_signature(
+                bundle.canonical_json(), bundle.signature, bundle.public_key_pem
+            )
+            if not sig_ok:
+                return False, "signature-verification-failed"
+
+        return True, "ok"
+
+    async def _fetch_entries(self, scope: ExportScope) -> list[dict[str, Any]]:
+        query = """
+            SELECT pe.event_id, pe.event_type, pe.session_id, pe.request_id,
+                   pe.occurred_at, pe.payload,
+                   COALESCE(pc.sequence, 0) AS sequence,
+                   COALESCE(pc.prev_hash, ?) AS prev_hash,
+                   COALESCE(pc.entry_hash, '') AS entry_hash
+            FROM provenance_events pe
+            LEFT JOIN provenance_chain pc ON pc.event_id = pe.event_id
+        """
+        conditions: list[str] = []
+        params: list[Any] = [CHAIN_GENESIS_HASH]
+
+        if scope.session_id:
+            conditions.append("pe.session_id = ?")
+            params.append(scope.session_id)
+        if scope.from_ts:
+            conditions.append("pe.occurred_at >= ?")
+            params.append(scope.from_ts)
+        if scope.to_ts:
+            conditions.append("pe.occurred_at <= ?")
+            params.append(scope.to_ts)
+
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+        query += " ORDER BY COALESCE(pc.sequence, 0), pe.occurred_at ASC"
+
+        try:
+            async with aiosqlite.connect(self._db_path) as db:
+                db.row_factory = aiosqlite.Row
+                async with db.execute(query, params) as cur:
+                    rows = await cur.fetchall()
+            return [dict(r) for r in rows]
+        except Exception as e:
+            logger.error("export fetch failed: %s", e)
+            return []
+
+    def _to_chain_entries(self, entries: list[dict[str, Any]]) -> list[ChainEntry]:
+        return [
+            ChainEntry(
+                sequence=e.get("sequence", i),
+                event_id=e.get("event_id", ""),
+                payload_json=e.get("payload", "{}"),
+                prev_hash=e.get("prev_hash", CHAIN_GENESIS_HASH),
+                entry_hash=e.get("entry_hash", ""),
+            )
+            for i, e in enumerate(entries)
+        ]
+
+    def _build_chain_proof(self, entries: list[ChainEntry]) -> ChainProof:
+        if not entries:
+            return ChainProof(
+                first_sequence=0, last_sequence=0, entry_count=0,
+                first_hash=CHAIN_GENESIS_HASH, last_hash=CHAIN_GENESIS_HASH,
+            )
+        ok, err = verify_chain(entries, self._hmac_key)
+        return ChainProof(
+            first_sequence=entries[0].sequence,
+            last_sequence=entries[-1].sequence,
+            entry_count=len(entries),
+            first_hash=entries[0].entry_hash or CHAIN_GENESIS_HASH,
+            last_hash=entries[-1].entry_hash or CHAIN_GENESIS_HASH,
+            chain_valid=ok,
+            chain_error=err,
+        )
+
+    def _collect_fired_rules(self, entries: list[dict[str, Any]]) -> set[str]:
+        fired: set[str] = set()
+        for entry in entries:
+            try:
+                payload = json.loads(entry.get("payload", "{}"))
+                rule_name = payload.get("rule_name", "")
+                if rule_name:
+                    fired.add(rule_name)
+            except (json.JSONDecodeError, TypeError):
+                pass
+        return fired
+
+    def _build_retention_policy(self, framework: str | None) -> RetentionPolicy:
+        from context_firewall.compliance.baa import BAA_MIN_RETENTION_DAYS, enforce_baa_retention
+        base_days = 365
+        if framework in ("hipaa", "fedramp"):
+            base_days = 2190  # 6 years
+        elif framework == "soc2":
+            base_days = 365  # 1 year typical
+        if self._baa_mode:
+            effective, overridden = enforce_baa_retention(base_days)
+            return RetentionPolicy(
+                retention_days=effective,
+                baa_override_applied=overridden,
+                framework=framework or "",
+            )
+        return RetentionPolicy(retention_days=base_days, framework=framework or "")

context_firewall/compliance/keys.py

@@ -0,0 +1,94 @@
+"""Ed25519 keypair management for compliance bundle signing.
+
+Key store: encrypted private key written to <key_dir>/signing.key.enc
+Public key exported as PEM to <key_dir>/signing.pub
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_KEY_DIR = Path(".ctxfw/keys")
+
+
+def generate_keypair(key_dir: Path = _DEFAULT_KEY_DIR) -> tuple[str, str]:
+    """Generate an Ed25519 signing keypair and persist to disk.
+
+    Returns (private_key_pem, public_key_pem).
+    """
+    key_dir.mkdir(parents=True, exist_ok=True)
+    private_key = Ed25519PrivateKey.generate()
+
+    private_pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    ).decode()
+
+    public_key = private_key.public_key()
+    public_pem = public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode()
+
+    (key_dir / "signing.key").write_text(private_pem)
+    (key_dir / "signing.key").chmod(0o600)
+    (key_dir / "signing.pub").write_text(public_pem)
+
+    logger.info("Ed25519 keypair generated in %s", key_dir)
+    return private_pem, public_pem
+
+
+def load_private_key(key_dir: Path = _DEFAULT_KEY_DIR) -> Ed25519PrivateKey | None:
+    key_path = key_dir / "signing.key"
+    if not key_path.exists():
+        return None
+    pem = key_path.read_bytes()
+    return serialization.load_pem_private_key(pem, password=None)
+
+
+def load_public_key_pem(key_dir: Path = _DEFAULT_KEY_DIR) -> str | None:
+    pub_path = key_dir / "signing.pub"
+    if not pub_path.exists():
+        return None
+    return pub_path.read_text()
+
+
+def sign_bundle(canonical_json: bytes, key_dir: Path = _DEFAULT_KEY_DIR) -> str | None:
+    """Sign canonical JSON with the tenant private key.
+
+    Returns base64-encoded Ed25519 signature, or None if no key exists.
+    """
+    private_key = load_private_key(key_dir)
+    if private_key is None:
+        return None
+    signature = private_key.sign(canonical_json)
+    return base64.b64encode(signature).decode()
+
+
+def verify_signature(
+    canonical_json: bytes,
+    signature_b64: str,
+    public_key_pem: str,
+) -> bool:
+    """Verify a bundle signature against the provided public key."""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    from cryptography.exceptions import InvalidSignature
+
+    pub_key = serialization.load_pem_public_key(public_key_pem.encode())
+    signature = base64.b64decode(signature_b64)
+    try:
+        pub_key.verify(signature, canonical_json)
+        return True
+    except InvalidSignature:
+        return False

context_firewall/config.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class SourceDeclaration(BaseModel):
+    """Declarative source definition - declared in ctxfw.yaml, registered on startup."""
+    id: str
+    type: str = "unknown"
+    trust_tier: str = "untrusted"
+    owner: str = ""
+    region: str = ""
+    data_classification: str = ""
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class DetectionConfig(BaseModel):
+    """Injection detector sensitivity knobs."""
+    injection_block_threshold: float = 0.55
+    injection_warn_threshold: float = 0.35
+    default_source_trust_tier: str = "untrusted"
+
+
+class EnforcementConfig(BaseModel):
+    """Trust penalty / reward tuning."""
+    penalty_increment: float = 0.15
+    decay_half_life_days: float = 1.0
+    reward_factor: float = 0.90
+
+
+class ComplianceFrameworksConfig(BaseModel):
+    """Maps data_classification keywords to compliance framework identifiers.
+
+    Override to add custom classifications or additional frameworks.
+    Keys are substrings matched against data_classification (case-insensitive).
+    """
+    classification_frameworks: dict[str, list[str]] = Field(
+        default_factory=lambda: {
+            "phi": ["hipaa"],
+            "pii": ["hipaa", "gdpr"],
+            "pci": ["pci-dss"],
+            "financial": ["sox", "fedramp"],
+            "federal": ["fedramp"],
+            "classified": ["fedramp"],
+            "sensitive": ["soc2"],
+            "internal_code": [],
+        }
+    )
+
+
+def _expand_env_vars(text: str) -> str:
+    """Expand ${VAR:-default} and ${VAR} patterns using os.environ."""
+    def _replace(m: re.Match) -> str:
+        var, _, default = m.group(1).partition(":-")
+        return os.environ.get(var, default)
+    return re.sub(r"\$\{([^}]+)\}", _replace, text)
+
+
+class DaemonJobConfig(BaseModel):
+    schedule: str
+    timeout_min: int = 30
+
+
+class DaemonIndexingConfig(BaseModel):
+    debounce_ms: int = 2000
+    max_batch_size: int = 100
+    max_concurrent_refreshes: int = 2
+
+
+class DaemonConfig(BaseModel):
+    pid_file: str = ".ctxfw/daemon.pid"
+    shutdown_timeout_sec: int = 30
+    indexing: DaemonIndexingConfig = Field(default_factory=DaemonIndexingConfig)
+    jobs: dict[str, DaemonJobConfig] = Field(default_factory=lambda: {
+        "entropy_computation": DaemonJobConfig(schedule="0 */6 * * *", timeout_min=30),
+        "weight_calibration": DaemonJobConfig(schedule="0 2 * * *", timeout_min=15),
+        "provenance_compaction": DaemonJobConfig(schedule="0 3 * * *", timeout_min=60),
+        "annotation_invalidation": DaemonJobConfig(schedule="0 * * * *", timeout_min=10),
+        "symbol_table_refresh": DaemonJobConfig(schedule="*/15 * * * *", timeout_min=2),
+        "runtime_signal_aggregation": DaemonJobConfig(schedule="*/30 * * * *", timeout_min=5),
+    })
+
+
+class RestApiAuthConfig(BaseModel):
+    enabled: bool = True
+    tokens: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class RestApiConfig(BaseModel):
+    port: int = 8080
+    read_timeout_sec: int = 30
+    write_timeout_sec: int = 60
+    auth: RestApiAuthConfig = Field(default_factory=RestApiAuthConfig)
+
+
+class McpConfig(BaseModel):
+    transport: str = "stdio"
+
+
+class GraphConfig(BaseModel):
+    max_depth: int = 4
+    max_nodes: int = 50
+    trust_cutoff: float = 0.30
+    traversal_timeout_ms: int = 100
+
+
+class TrustConfig(BaseModel):
+    weights: dict[str, float] = Field(default_factory=lambda: {
+        "structural_relevance": 0.30,
+        "runtime_evidence": 0.25,
+        "freshness": 0.10,
+        "stability": 0.10,
+        "verification": 0.10,
+        "consistency": 0.05,
+        "injection_risk": -0.05,
+        "entropy_contribution": -0.15,
+    })
+    fallback_score: float = 0.50
+    phase2_learning_rate: float = 0.05
+
+
+class EntropyConfig(BaseModel):
+    default_score: float = 0.30
+    high_entropy_threshold: float = 0.60
+    high_entropy_consecutive: int = 3
+    staleness_penalty: float = 0.15
+    analysis_cadence_hours: int = 6
+
+
+class PolicyConfig(BaseModel):
+    policy_dir: str = ".ctxfw/policies"
+    max_file_size_kb: int = 50
+    exempt_private_ips: bool = True
+    cross_repo_auth_required: bool = True
+
+
+class ProvenanceConfig(BaseModel):
+    queue_size: int = 10_000
+    session_timeout_min: int = 30
+    archival_after_days: int = 90
+
+
+class SynthesizerConfig(BaseModel):
+    default_budget: int = 80_000
+    reserve_for_summary: int = 500
+    per_task_budgets: dict[str, int] = Field(default_factory=lambda: {
+        "BUG_FIX": 60_000,
+        "NEW_FEATURE": 80_000,
+        "REFACTOR": 100_000,
+        "SECURITY_REVIEW": 50_000,
+        "DEPENDENCY_AUDIT": 40_000,
+    })
+
+
+class OtelConfig(BaseModel):
+    enabled: bool = True
+    grpc_port: int = 4317
+    http_port: int = 4318
+    queue_size: int = 10_000
+    consumer_workers: int = 4
+    trace_assembly_timeout_sec: int = 30
+    signal_batch_flush_ms: int = 500
+    signal_batch_size: int = 100
+    fuzzy_threshold: float = 0.75
+    latency_degraded_threshold_ms: int = 2000
+    exception_rate_high_threshold: float = 0.10
+
+
+class AnalyticsConfig(BaseModel):
+    enabled: bool = True
+    degradation_threshold: float = 0.15
+    degradation_window_days: int = 30
+    entropy_trend_snapshots: int = 5
+    high_entropy_threshold: float = 0.60
+    high_entropy_consecutive: int = 3
+
+
+class StorageConfig(BaseModel):
+    db_path: str = ".ctxfw/cre.db"
+    object_storage_bucket: str = ""
+    object_storage_prefix: str = "cre-provenance/"
+
+
+class ControlPlaneConfig(BaseModel):
+    """Optional connection to the ContextWall control plane.
+
+    Leave url empty to run in fully local mode (no data leaves the host).
+    The registration_token is issued from the webapp Settings page.
+    """
+    url: str = ""
+    registration_token: str = ""
+    daemon_name: str = ""
+    push_interval_seconds: int = 60
+    heartbeat_interval_seconds: int = 30
+    policy_pull: bool = True
+
+
+class Config(BaseModel):
+    repository_root: str = "."
+    compliance_hmac_key: str = ""
+    sources: list[SourceDeclaration] = Field(default_factory=list)
+    detection: DetectionConfig = Field(default_factory=DetectionConfig)
+    enforcement: EnforcementConfig = Field(default_factory=EnforcementConfig)
+    compliance: ComplianceFrameworksConfig = Field(default_factory=ComplianceFrameworksConfig)
+    daemon: DaemonConfig = Field(default_factory=DaemonConfig)
+    rest_api: RestApiConfig = Field(default_factory=RestApiConfig)
+    mcp: McpConfig = Field(default_factory=McpConfig)
+    graph: GraphConfig = Field(default_factory=GraphConfig)
+    trust: TrustConfig = Field(default_factory=TrustConfig)
+    entropy: EntropyConfig = Field(default_factory=EntropyConfig)
+    policy: PolicyConfig = Field(default_factory=PolicyConfig)
+    provenance: ProvenanceConfig = Field(default_factory=ProvenanceConfig)
+    synthesizer: SynthesizerConfig = Field(default_factory=SynthesizerConfig)
+    otel: OtelConfig = Field(default_factory=OtelConfig)
+    analytics: AnalyticsConfig = Field(default_factory=AnalyticsConfig)
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    control_plane: ControlPlaneConfig = Field(default_factory=ControlPlaneConfig)
+
+
+def load_config(config_path: str | Path = "ctxfw.yaml") -> Config:
+    path = Path(config_path)
+    if not path.exists():
+        return Config()
+    with path.open() as f:
+        content = _expand_env_vars(f.read())
+    raw = yaml.safe_load(content) or {}
+    return Config.model_validate(raw)