fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/standalone_license_installation.py

@@ -0,0 +1,177 @@
+"""Install a verified capability token or installation entitlement through Key Vault.
+
+The managed host reads the token from standard input, verifies it against the packaged
+upstream key and the exact deployment bindings, writes it to the fixed Key Vault
+secret, and verifies the stored content again before any runtime consumes it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli import standalone_planned_outputs
+from fdai_deployment_cli.license import (
+    INSTALLATION_ENTITLEMENT_SCHEMA,
+    inspect_installation_entitlement,
+    inspect_license,
+    signed_token_schema,
+)
+from fdai_deployment_cli.standalone_host_state import private_json, replace_private_json
+from fdai_deployment_cli.standalone_host_values import vault_name
+from fdai_deployment_cli.trust_roots import license_public_key_pem
+
+LICENSE_SECRET_NAME = "fdai-capability-license"
+
+
+def install_license(
+    args: argparse.Namespace,
+    work_dir: Path,
+    *,
+    login: Callable[[dict[str, object], Path], None],
+) -> dict[str, object]:
+    """Store one verified token and record the Container Apps license variables."""
+
+    context = private_json(work_dir / "context.json", "standalone host context")
+    login(context, work_dir)
+    token = sys.stdin.read(8193)
+    if len(token) > 8192 or token != token.strip():
+        raise ValueError("license token stdin is invalid")
+    _inspect(token, args)
+    token_digest = hashlib.sha256(token.encode("ascii")).hexdigest()
+    infra = Path(str(context["infra"]))
+    key_vault = vault_name(_output(infra, "key_vault_uri"))
+    result = subprocess.run(
+        (
+            "az",
+            "keyvault",
+            "secret",
+            "set",
+            "--vault-name",
+            key_vault,
+            "--name",
+            LICENSE_SECRET_NAME,
+            "--file",
+            "/dev/stdin",
+            "--encoding",
+            "utf-8",
+            "--query",
+            "id",
+            "--output",
+            "tsv",
+            "--only-show-errors",
+        ),
+        input=token,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    token = ""
+    if result.returncode != 0:
+        raise ValueError("license token Key Vault installation failed")
+    versioned_secret_id = result.stdout.strip()
+    match = re.fullmatch(
+        rf"https://{re.escape(key_vault)}[.]vault[.]azure[.]net/secrets/"
+        rf"{LICENSE_SECRET_NAME}/([0-9a-f]{{32}})",
+        versioned_secret_id,
+    )
+    if match is None:
+        raise ValueError("license token Key Vault readback is invalid")
+    readback = subprocess.run(
+        (
+            "az",
+            "keyvault",
+            "secret",
+            "show",
+            "--id",
+            versioned_secret_id,
+            "--query",
+            "value",
+            "--output",
+            "tsv",
+            "--only-show-errors",
+        ),
+        cwd=work_dir,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    if readback.returncode != 0:
+        raise ValueError("license token Key Vault content readback failed")
+    stored = readback.stdout.strip()
+    _inspect(stored, args)
+    if hashlib.sha256(stored.encode("ascii")).hexdigest() != token_digest:
+        raise ValueError("license token Key Vault content differs")
+    values = private_json(work_dir / "application.auto.tfvars.json", "application variables")
+    values["license"] = {
+        "token_secret_id": versioned_secret_id.rsplit("/", 1)[0],
+        "image_digest": args.image_digest,
+        "deployment_digest": args.deployment_binding,
+        "token_revision": hashlib.sha256(
+            f"{args.image_digest}:{args.deployment_binding}".encode()
+        ).hexdigest(),
+    }
+    replace_private_json(work_dir / "application.auto.tfvars.json", values)
+    return {
+        "schema_version": "fdai.standalone-license-installation.v1",
+        "state": "installed",
+        "secret_metadata_verified": True,
+        "secret_content_verified": True,
+        "mutation_performed": True,
+        "subscription_ready": False,
+    }
+
+
+def aks_license_environment(
+    application_values: dict[str, Any],
+) -> tuple[dict[str, str], dict[str, str]]:
+    """Return Core's plain and Key Vault-backed license environment once a token is installed."""
+
+    license_values = application_values.get("license")
+    if not isinstance(license_values, dict) or not license_values.get("token_secret_id"):
+        return {}, {}
+    return (
+        {
+            "FDAI_LICENSE_IMAGE_DIGEST": str(license_values["image_digest"]),
+            "FDAI_LICENSE_TOKEN_REVISION": str(license_values["token_revision"]),
+        },
+        {"FDAI_LICENSE_TOKEN": LICENSE_SECRET_NAME},
+    )
+
+
+def _inspect(token: str, args: argparse.Namespace) -> None:
+    if signed_token_schema(token) == INSTALLATION_ENTITLEMENT_SCHEMA:
+        installation_binding = getattr(args, "installation_binding", None)
+        if not installation_binding:
+            raise ValueError("an installation entitlement requires its installation binding")
+        inspect_installation_entitlement(
+            token,
+            public_key_pem=license_public_key_pem(),
+            expected_installation_binding=installation_binding,
+            expected_deployment_binding=args.deployment_binding,
+        )
+        return
+    inspect_license(
+        token,
+        public_key_pem=license_public_key_pem(),
+        expected_image_digest=args.image_digest,
+        expected_tenant_binding=args.deployment_binding,
+    )
+
+
+def _output(infra: Path, name: str) -> str:
+    value = standalone_planned_outputs.read_output(
+        infra, name, raw=True, reason="Terraform output readback failed"
+    )
+    return str(value)
+
+
+__all__ = ["LICENSE_SECRET_NAME", "aks_license_environment", "install_license"]

fdai_deployment_cli/standalone_management_egress.py

@@ -0,0 +1,83 @@
+"""Derive the AKS API server authorized range from the managed host's egress.
+
+The AKS baseline keeps a public API server with authorized IP ranges. Only the managed deployment
+host runs Terraform, ``kubectl``, and readback against it, and that host leaves the operations
+network through its NAT gateway. The range is therefore the NAT gateway's single public address,
+read back from Azure Resource Manager rather than from any external address-echo service.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+
+
+def management_egress_cidrs(context: Mapping[str, object], *, cwd: Path) -> list[str]:
+    """Return the one ``/32`` range of the operations NAT gateway, or fail closed."""
+
+    ops_resource_group = str(context["state_resource_group"])
+    subscription_id = str(context["subscription_id"])
+    listed = _az(
+        (
+            "network",
+            "nat",
+            "gateway",
+            "list",
+            "--resource-group",
+            ops_resource_group,
+            "--subscription",
+            subscription_id,
+            "--query",
+            "[].publicIpAddresses[].id",
+            "--output",
+            "json",
+        ),
+        cwd,
+    )
+    try:
+        addresses = json.loads(listed)
+    except json.JSONDecodeError as exc:
+        raise ValueError("management NAT gateway readback is invalid") from exc
+    if not isinstance(addresses, list) or len(addresses) != 1 or not isinstance(addresses[0], str):
+        raise ValueError("management egress requires exactly one NAT gateway public IP")
+    raw = _az(
+        (
+            "network",
+            "public-ip",
+            "show",
+            "--ids",
+            addresses[0],
+            "--query",
+            "ipAddress",
+            "--output",
+            "tsv",
+        ),
+        cwd,
+    ).strip()
+    try:
+        address = ipaddress.IPv4Address(raw)
+    except ValueError as exc:
+        raise ValueError("management NAT gateway public IP is invalid") from exc
+    if not address.is_global:
+        raise ValueError("management NAT gateway public IP is not globally routable")
+    return [f"{address}/32"]
+
+
+def _az(arguments: tuple[str, ...], cwd: Path) -> str:
+    result = subprocess.run(
+        ("az", *arguments, "--only-show-errors"),
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    if result.returncode != 0:
+        raise ValueError("management egress readback failed")
+    return result.stdout
+
+
+__all__ = ["management_egress_cidrs"]

fdai_deployment_cli/standalone_migration_evidence.py

@@ -0,0 +1,38 @@
+"""Check the adoption evidence one service migration bootstrap may write."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fdai_deployment_cli.standalone_host_state import private_json
+
+
+def verify_service_evidence(evidence: Path, service: str) -> bool:
+    """Verify fresh adoption evidence; return False when the lineage was already adopted.
+
+    `bootstrap` writes adoption evidence only when it adopts a legacy baseline. When an earlier
+    run already adopted the service lineage, bootstrap only advances it to head and writes
+    nothing, so absent evidence is a verified resume rather than a failure. A partial or
+    inconsistent pair still fails closed.
+    """
+
+    migration_path = evidence / f"{service}.json"
+    schema_path = evidence / f"{service}-schema.json"
+    if not migration_path.exists() and not schema_path.exists():
+        return False
+    for path in (migration_path, schema_path):
+        path.chmod(0o600)
+    migration = private_json(migration_path, f"{service} migration evidence")
+    schema = private_json(schema_path, f"{service} migration schema")
+    if (
+        migration.get("service_id") != service
+        or not isinstance(migration.get("observed_schema_fingerprint"), str)
+        or schema.get("schema_version") != 1
+        or schema.get("service_id") != service
+        or schema.get("observed_schema_fingerprint") != migration.get("observed_schema_fingerprint")
+    ):
+        raise ValueError("service migration evidence is incomplete")
+    return True
+
+
+__all__ = ["verify_service_evidence"]

fdai_deployment_cli/standalone_operational_evidence.py

@@ -0,0 +1,356 @@
+"""AKS workload rendering for the independent operational evidence verifier."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any
+
+_GUID = re.compile(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}")
+_OPERATIONAL_EVIDENCE_PORT = 8791
+_OPERATIONAL_EVIDENCE_READINESS_PATH = "/v1/operational-evidence/readiness"
+_SERVICE_DATABASE_ROLES = {
+    "core": "fdai_core",
+    "core-control-plane": "fdai_core",
+    "operator": "fdai_operator",
+    "operator-service": "fdai_operator",
+    "executor": "fdai_executor",
+    "isolated-executor": "fdai_executor",
+    "ingestion": "fdai_ingestion_api",
+    "document-ingestion-api": "fdai_ingestion_api",
+    "worker": "fdai_ingestion_worker",
+    "document-processing-worker": "fdai_ingestion_worker",
+}
+
+
+def bind_service_database_role(service: str, environment: Mapping[str, object]) -> dict[str, str]:
+    """Return one workload environment with its service-owned PostgreSQL role."""
+
+    runtime_environment = {name: str(value) for name, value in environment.items()}
+    database_role = _SERVICE_DATABASE_ROLES.get(service)
+    if database_role is not None:
+        runtime_environment["FDAI_DATABASE_ROLE"] = database_role
+        runtime_environment["PGOPTIONS"] = f"-c role={database_role}"
+    return runtime_environment
+
+
+def aks_workload(
+    component: str,
+    refs: dict[str, Any],
+    identity: dict[str, Any],
+    environment: Mapping[str, object],
+    secret_environment: Mapping[str, str],
+    readiness_path: str,
+    liveness_path: str,
+    *,
+    external: bool = False,
+    service_port: int | None = None,
+    fs_group: int | None = None,
+    additional_identities: dict[str, dict[str, Any]] | None = None,
+    sidecars: dict[str, dict[str, object]] | None = None,
+) -> dict[str, object]:
+    """Build one runtime-neutral AKS long-running workload specification."""
+
+    image_names = {
+        "core": "core-control-plane",
+        "operator": "operator-service",
+        "executor": "isolated-executor",
+        "ingestion": "document-ingestion-api",
+        "worker": "document-processing-worker",
+    }
+    image_name = image_names.get(component)
+    if image_name is None or not isinstance(refs.get(image_name), str):
+        raise ValueError(f"AKS {component} workload image is unavailable")
+    cpu, memory = {
+        "core": ("1000m", "2Gi"),
+        "operator": ("500m", "1Gi"),
+        "executor": ("500m", "1Gi"),
+        "ingestion": ("500m", "1Gi"),
+        "worker": ("500m", "1Gi"),
+    }[component]
+    runtime_environment = bind_service_database_role(image_name, environment)
+    runtime_environment["FDAI_EXECUTION_VENUE"] = "deployed"
+    return {
+        "component": component,
+        "image": refs[image_name],
+        "identity_resource_id": identity["resource_id"],
+        "identity_client_id": identity["client_id"],
+        "additional_identities": additional_identities or {},
+        "command": [],
+        "args": [],
+        "replicas": 2,
+        "max_replicas": 4,
+        "cpu": cpu,
+        "memory": memory,
+        "port": 8000,
+        "service_port": service_port,
+        "external": external,
+        "readiness_path": readiness_path,
+        "liveness_path": liveness_path,
+        "fs_group": fs_group,
+        "environment": runtime_environment,
+        "secret_environment": secret_environment,
+        "sidecars": sidecars or {},
+    }
+
+
+def aks_operational_evidence_verifier_workload(
+    *,
+    refs: dict[str, Any],
+    verifier_identity: object,
+    core_identity: dict[str, Any],
+    executor_identity: object,
+    deploy_runner_principal: str,
+    application_values: dict[str, Any],
+    postgres_fqdn: str,
+    postgres_database: str,
+) -> dict[str, object] | None:
+    """Render the optional non-agent verifier workload from deployment-owned bindings."""
+
+    binding = application_values.get("operational_evidence_verifier")
+    if binding is None:
+        return None
+    if not isinstance(binding, dict) or binding.get("enabled") is not True:
+        raise ValueError("operational evidence verifier binding is invalid")
+    if not isinstance(verifier_identity, dict):
+        raise TypeError("operational evidence verifier identity is unavailable")
+
+    verifier = _identity_binding(verifier_identity, "operational evidence verifier identity")
+    core = _identity_binding(core_identity, "Core runtime identity")
+    if isinstance(executor_identity, dict):
+        executor_principal = _identity_binding(executor_identity, "isolated executor identity")[
+            "principal_id"
+        ]
+    else:
+        executor_principal = _anchor_principal(
+            binding.get("anchors_json"), "anchor:isolated-executor"
+        )
+    if verifier["principal_id"] in {
+        core["principal_id"],
+        executor_principal,
+        deploy_runner_principal,
+    }:
+        raise ValueError("operational evidence verifier identity overlaps an independent anchor")
+
+    json_fields = {
+        "anchors_json": "FDAI_OPERATIONAL_EVIDENCE_ANCHORS_JSON",
+        "caller_token_jwks_json": "FDAI_OPERATIONAL_EVIDENCE_CALLER_TOKEN_JWKS_JSON",
+        "role_readback_scopes_json": "FDAI_OPERATIONAL_EVIDENCE_ROLE_READBACK_SCOPES_JSON",
+        "allowed_role_scopes_json": "FDAI_OPERATIONAL_EVIDENCE_ALLOWED_ROLE_SCOPES_JSON",
+        "vertical_executor_principals_json": (
+            "FDAI_OPERATIONAL_EVIDENCE_VERTICAL_EXECUTOR_PRINCIPALS_JSON"
+        ),
+        "writer_members_json": "FDAI_OPERATIONAL_EVIDENCE_WRITER_MEMBERS_JSON",
+    }
+    optional_fields = {
+        "grant_registry_json": "FDAI_OPERATIONAL_EVIDENCE_GRANT_REGISTRY_JSON",
+        "observation_metric_workspace_id": (
+            "FDAI_OPERATIONAL_EVIDENCE_OBSERVATION_METRIC_WORKSPACE_ID"
+        ),
+        "observation_metric_queries_json": (
+            "FDAI_OPERATIONAL_EVIDENCE_OBSERVATION_METRIC_QUERIES_JSON"
+        ),
+        "observation_scope_rows_json": "FDAI_OPERATIONAL_EVIDENCE_OBSERVATION_SCOPE_ROWS_JSON",
+        "forecast_history_sources_json": "FDAI_FORECAST_HISTORY_SOURCES_JSON",
+    }
+    environment: dict[str, object] = {
+        "AZURE_CLIENT_ID": verifier["client_id"],
+        "FDAI_MI_CLIENT_ID": verifier["client_id"],
+        "POSTGRES_HOST": postgres_fqdn,
+        "POSTGRES_DATABASE": postgres_database,
+        "FDAI_DATABASE_ROLE": "fdai_operational_evidence_verifier",
+        "PGOPTIONS": "-c role=fdai_operational_evidence_verifier",
+        "RUNTIME_ENV": application_values["env"],
+        "FDAI_OPERATIONAL_EVIDENCE_ENABLED": "1",
+        "FDAI_OPERATIONAL_EVIDENCE_TRUST_REGISTRY_PATH": _optional_text(
+            binding,
+            "trust_registry_path",
+            default="config/operational-evidence-trust-registry.json",
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_TRUST_REGISTRY_PIN": _required_text(
+            binding, "trust_registry_pin"
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_GRANT_REGISTRY_PATH": _required_text(
+            binding, "grant_registry_path"
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_GRANT_REGISTRY_PIN": _required_text(
+            binding, "grant_registry_pin"
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_VERIFIER_URL": (
+            f"http://127.0.0.1:{_OPERATIONAL_EVIDENCE_PORT}"
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_READER_ROLE": "fdai_core",
+        "FDAI_OPERATIONAL_EVIDENCE_CORE_EXECUTOR_PRINCIPAL_ID": core["principal_id"],
+        "FDAI_OPERATIONAL_EVIDENCE_ISOLATED_EXECUTOR_PRINCIPAL_ID": executor_principal,
+        "FDAI_OPERATIONAL_EVIDENCE_DEV_GATEWAY_EXECUTOR_PRINCIPAL_ID": _required_text(
+            binding, "dev_gateway_executor_principal_id"
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_DEPLOY_RUNNER_PRINCIPAL_ID": deploy_runner_principal,
+        "FDAI_OPERATIONAL_EVIDENCE_CALLER_TOKEN_ISSUER": _required_text(
+            binding, "caller_token_issuer"
+        ),
+        "FDAI_OPERATIONAL_EVIDENCE_CALLER_TOKEN_AUDIENCE": _required_text(
+            binding, "caller_token_audience"
+        ),
+    }
+    for key, env_name in json_fields.items():
+        environment[env_name] = _required_json_text(binding, key)
+    for key, env_name in optional_fields.items():
+        if key in binding:
+            environment[env_name] = (
+                _required_text(binding, key)
+                if key == "observation_metric_workspace_id"
+                else _required_json_text(binding, key)
+            )
+    vertical_principals = json.loads(
+        str(environment["FDAI_OPERATIONAL_EVIDENCE_VERTICAL_EXECUTOR_PRINCIPALS_JSON"])
+    )
+    if not isinstance(vertical_principals, list) or not all(
+        isinstance(principal, str) and _GUID.fullmatch(principal) is not None
+        for principal in vertical_principals
+    ):
+        raise ValueError("vertical_executor_principals_json must be a JSON list of GUIDs")
+    environment["FDAI_OPERATIONAL_EVIDENCE_EXECUTOR_PRINCIPALS_JSON"] = json.dumps(
+        sorted(
+            {
+                str(environment["FDAI_OPERATIONAL_EVIDENCE_CORE_EXECUTOR_PRINCIPAL_ID"]),
+                str(environment["FDAI_OPERATIONAL_EVIDENCE_ISOLATED_EXECUTOR_PRINCIPAL_ID"]),
+                str(environment["FDAI_OPERATIONAL_EVIDENCE_DEV_GATEWAY_EXECUTOR_PRINCIPAL_ID"]),
+                deploy_runner_principal,
+                *vertical_principals,
+            }
+        ),
+        separators=(",", ":"),
+    )
+    image = refs.get("core-control-plane")
+    if not isinstance(image, str):
+        raise TypeError("AKS operational evidence verifier image is unavailable")
+    return {
+        "component": "operational-evidence-verifier",
+        "image": image,
+        "identity_resource_id": verifier["resource_id"],
+        "identity_client_id": verifier["client_id"],
+        "additional_identities": {},
+        "command": ["python", "-m", "fdai.delivery.operational_evidence_server"],
+        "args": ["--host", "0.0.0.0", "--port", str(_OPERATIONAL_EVIDENCE_PORT)],
+        "replicas": 1,
+        "max_replicas": 1,
+        "cpu": "500m",
+        "memory": "1Gi",
+        "port": _OPERATIONAL_EVIDENCE_PORT,
+        "service_port": None,
+        "external": False,
+        "readiness_path": _OPERATIONAL_EVIDENCE_READINESS_PATH,
+        "liveness_path": _OPERATIONAL_EVIDENCE_READINESS_PATH,
+        "fs_group": None,
+        "environment": {
+            name: str(value)
+            for name, value in {**environment, "FDAI_EXECUTION_VENUE": "deployed"}.items()
+        },
+        "secret_environment": {"FDAI_OPERATIONAL_EVIDENCE_VERIFIER_DSN": "fdai-state-store-dsn"},
+        "sidecars": {},
+    }
+
+
+def add_aks_operational_evidence_verifier_workload(
+    workloads: dict[str, dict[str, object]],
+    *,
+    refs: dict[str, Any],
+    identities: dict[str, Any],
+    substrate_outputs: Mapping[str, object],
+    context: Mapping[str, object],
+    application_values: dict[str, Any],
+) -> None:
+    """Add the optional verifier workload to ``workloads`` when its binding is present."""
+
+    if application_values.get("operational_evidence_verifier") is None:
+        return
+    verifier_workload = aks_operational_evidence_verifier_workload(
+        refs=refs,
+        verifier_identity=substrate_outputs["operational_evidence_verifier_identity"],
+        core_identity=_mapping(identities.get("core"), "Core runtime identity"),
+        executor_identity=identities.get("executor"),
+        deploy_runner_principal=_required_text(context, "principal_id"),
+        application_values=application_values,
+        postgres_fqdn=_required_text(substrate_outputs, "postgres_fqdn"),
+        postgres_database=_required_text(substrate_outputs, "postgres_database"),
+    )
+    if verifier_workload is not None:
+        workloads["operational-evidence-verifier"] = verifier_workload
+
+
+def runtime_principal_ids_with_operational_evidence_verifier(
+    identities: Mapping[str, Any], names: tuple[str, ...]
+) -> set[str]:
+    """Return runtime principal ids, including the optional verifier identity."""
+
+    principals = {
+        str(_mapping(identities.get(name), f"{name} runtime identity")["principal_id"])
+        for name in names
+    }
+    verifier_identity = identities.get("operational_evidence_verifier")
+    if verifier_identity is not None:
+        principals.add(
+            str(
+                _mapping(verifier_identity, "operational evidence verifier runtime identity")[
+                    "principal_id"
+                ]
+            )
+        )
+    return principals
+
+
+def _mapping(value: object, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ValueError(f"{label} is invalid")
+    return {str(key): item for key, item in value.items()}
+
+
+def _identity_binding(value: dict[str, Any], label: str) -> dict[str, str]:
+    result = {
+        "resource_id": _required_text(value, "resource_id"),
+        "client_id": _required_text(value, "client_id"),
+        "principal_id": _required_text(value, "principal_id"),
+    }
+    if any(_GUID.fullmatch(result[key]) is None for key in ("client_id", "principal_id")):
+        raise ValueError(f"{label} is invalid")
+    return result
+
+
+def _required_text(value: Mapping[str, Any], key: str) -> str:
+    item = value.get(key)
+    if not isinstance(item, str) or not item.strip():
+        raise ValueError(f"{key} is required")
+    return item.strip()
+
+
+def _optional_text(value: Mapping[str, Any], key: str, *, default: str) -> str:
+    item = value.get(key, default)
+    if not isinstance(item, str) or not item.strip():
+        raise ValueError(f"{key} is required")
+    return item.strip()
+
+
+def _required_json_text(value: Mapping[str, Any], key: str) -> str:
+    item = _required_text(value, key)
+    try:
+        json.loads(item)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{key} must be valid JSON") from exc
+    return item
+
+
+def _anchor_principal(anchors_json: object, anchor_id: str) -> str:
+    if isinstance(anchors_json, str) and anchors_json.strip():
+        try:
+            parsed = json.loads(anchors_json)
+        except json.JSONDecodeError:
+            parsed = None
+        if isinstance(parsed, dict) and isinstance(parsed.get("anchors"), list):
+            for entry in parsed["anchors"]:
+                if isinstance(entry, dict) and entry.get("anchor_id") == anchor_id:
+                    principal = entry.get("principal_id")
+                    if isinstance(principal, str) and _GUID.fullmatch(principal) is not None:
+                        return principal
+    raise TypeError("operational evidence verifier requires the isolated executor anchor")