openmapstack 0.2.0__py3-none-any.whl

openmapstack/expectations.py

@@ -0,0 +1,284 @@
+"""Attested, project-specific expectations for user-data verification.
+
+An expectation supplies the golden answer that a generic checker cannot know.
+The pipeline being checked must not certify that answer itself, so execution is
+licensed only by an attestation bound to both the check/arguments and the
+project's current input hash.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .checks import AssertionResult, failed, not_testable, passed, warning
+from .checks import geodata as geodata_checks
+from .integrity import normalize_digest, sha256_file
+from .project import get_in, project_path
+
+ExpectationCheck = Callable[..., AssertionResult]
+
+EXPECTATION_CHECKS: dict[str, ExpectationCheck] = {
+    "geodata.row_count": geodata_checks.row_count,
+    "geodata.feature_present": geodata_checks.feature_present,
+    "geodata.feature_absent": geodata_checks.feature_absent,
+    "geodata.feature_field_equals": geodata_checks.feature_field_equals,
+    "geodata.field_range": geodata_checks.field_range,
+}
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_RESERVED_ARGS = {"workspace", "project_dir"}
+
+
+def expectation_digest(check: str, args: dict[str, Any]) -> str:
+    """Bind an attestation to the exact check and arguments it reviewed."""
+    canonical = json.dumps(
+        {"check": check, "args": args},
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        default=str,
+    ).encode("utf-8")
+    return f"sha256:{hashlib.sha256(canonical).hexdigest()}"
+
+
+def _evidence(
+    evidence_class: str,
+    *,
+    attestation: dict[str, Any] | None,
+    expected_expectation_hash: str,
+) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "class": evidence_class,
+        "expected_expectation_sha256": expected_expectation_hash,
+    }
+    if isinstance(attestation, dict):
+        for key in ("verified_by", "verified_against", "verified_at", "evidence_sha256"):
+            value = attestation.get(key)
+            if value not in (None, ""):
+                result[key] = value
+    return result
+
+
+def _validate_args(
+    root: Path,
+    check: str,
+    args: object,
+) -> tuple[dict[str, Any] | None, AssertionResult | None]:
+    if not isinstance(args, dict):
+        return None, failed("expectation args must be a mapping", code="expectation_args_invalid")
+    if _RESERVED_ARGS & set(args):
+        return None, failed(
+            f"expectation args contain reserved names: {sorted(_RESERVED_ARGS & set(args))}",
+            code="expectation_args_invalid",
+        )
+    rules: dict[str, tuple[set[str], set[str]]] = {
+        "geodata.row_count": (
+            {"path", "equals", "at_least", "at_most"},
+            {"path"},
+        ),
+        "geodata.feature_present": ({"path", "id_field", "id"}, {"path", "id_field", "id"}),
+        "geodata.feature_absent": ({"path", "id_field", "id"}, {"path", "id_field", "id"}),
+        "geodata.feature_field_equals": (
+            {"path", "id_field", "id", "field", "equals"},
+            {"path", "id_field", "id", "field", "equals"},
+        ),
+        "geodata.field_range": ({"path", "field", "min", "max"}, {"path", "field"}),
+    }
+    allowed, required = rules[check]
+    extra = set(args) - allowed
+    missing = required - set(args)
+    if extra or missing:
+        return None, failed(
+            f"expectation args have extra={sorted(extra)} missing={sorted(missing)}",
+            code="expectation_args_invalid",
+        )
+    if check == "geodata.row_count":
+        constraints = [args.get(key) for key in ("equals", "at_least", "at_most") if key in args]
+        if not constraints or any(isinstance(value, bool) or not isinstance(value, int) or value < 0 for value in constraints):
+            return None, failed(
+                "row_count requires at least one non-negative integer constraint",
+                code="expectation_args_invalid",
+            )
+    if check == "geodata.field_range":
+        bounds = [args.get(key) for key in ("min", "max") if key in args]
+        if not bounds or any(isinstance(value, bool) or not isinstance(value, (int, float)) for value in bounds):
+            return None, failed(
+                "field_range requires at least one numeric min/max bound",
+                code="expectation_args_invalid",
+            )
+    path = args.get("path")
+    if project_path(root, path) is None:
+        return None, failed(
+            "expectation path must be safe and project-relative",
+            code="expectation_path_unsafe",
+        )
+    for key in ("field", "id_field"):
+        value = args.get(key)
+        if value is not None and (not isinstance(value, str) or _IDENTIFIER.fullmatch(value) is None):
+            return None, failed(
+                f"expectation {key} must be a simple identifier",
+                code="expectation_args_invalid",
+            )
+    return dict(args), None
+
+
+def evaluate_expectation(
+    root: Path,
+    manifest: dict[str, Any],
+    expectation: object,
+) -> tuple[AssertionResult, dict[str, Any]]:
+    """Validate an attestation, then execute its allowlisted checker.
+
+    Returns the assertion result plus structured evidence for the verification
+    report. Unverified, incomplete, or stale attestations are warnings and do
+    not execute model- or user-supplied expected values.
+    """
+    if not isinstance(expectation, dict):
+        return failed("expectation must be a mapping", code="expectation_invalid"), {
+            "class": "invalid"
+        }
+
+    check = expectation.get("check")
+    args = expectation.get("args")
+    expectation_id = expectation.get("id")
+    if not isinstance(expectation_id, str) or not expectation_id.strip():
+        return failed("expectation id is required", code="expectation_invalid"), {
+            "class": "invalid"
+        }
+    if not isinstance(check, str) or check not in EXPECTATION_CHECKS:
+        return failed(
+            f"expectation {expectation_id!r} uses an unsupported check {check!r}",
+            code="expectation_check_unsupported",
+        ), {"class": "invalid"}
+    if not isinstance(args, dict):
+        return failed(
+            f"expectation {expectation_id!r} args must be a mapping",
+            code="expectation_args_invalid",
+        ), {"class": "invalid"}
+
+    expected_hash = expectation_digest(check, args)
+    attestation = expectation.get("attestation")
+    if not isinstance(attestation, dict) or attestation.get("status") != "verified":
+        evidence = _evidence(
+            "unverified",
+            attestation=attestation if isinstance(attestation, dict) else None,
+            expected_expectation_hash=expected_hash,
+        )
+        return warning(
+            f"expectation {expectation_id!r} is unverified; independent review must bind "
+            f"expectation_sha256 to {expected_hash}",
+            code="expectation_unverified",
+        ), evidence
+
+    required_attestation = (
+        "verified_by",
+        "verified_against",
+        "verified_at",
+        "evidence_sha256",
+        "expectation_sha256",
+        "inputs_hash",
+    )
+    missing = [key for key in required_attestation if not attestation.get(key)]
+    if missing:
+        evidence = _evidence(
+            "unverified",
+            attestation=attestation,
+            expected_expectation_hash=expected_hash,
+        )
+        return warning(
+            f"expectation {expectation_id!r} has incomplete verification evidence: {missing}",
+            code="expectation_attestation_incomplete",
+        ), evidence
+
+    if normalize_digest(attestation.get("expectation_sha256")) != expected_hash:
+        evidence = _evidence(
+            "stale_attestation",
+            attestation=attestation,
+            expected_expectation_hash=expected_hash,
+        )
+        return warning(
+            f"expectation {expectation_id!r} changed after review; expected digest is {expected_hash}",
+            code="expectation_changed",
+        ), evidence
+
+    current_inputs_hash = normalize_digest(get_in(manifest, "runs", "latest", "inputs_hash"))
+    attested_inputs_hash = normalize_digest(attestation.get("inputs_hash"))
+    if current_inputs_hash is None or attested_inputs_hash != current_inputs_hash:
+        evidence = _evidence(
+            "stale_attestation",
+            attestation=attestation,
+            expected_expectation_hash=expected_hash,
+        )
+        evidence["current_inputs_hash"] = current_inputs_hash
+        return warning(
+            f"expectation {expectation_id!r} was not verified against the current project inputs",
+            code="expectation_inputs_changed",
+        ), evidence
+
+    normalized_evidence_hash = normalize_digest(attestation.get("evidence_sha256"))
+    if normalized_evidence_hash is None:
+        return warning(
+            f"expectation {expectation_id!r} has a malformed evidence digest",
+            code="expectation_attestation_incomplete",
+        ), _evidence(
+            "unverified",
+            attestation=attestation,
+            expected_expectation_hash=expected_hash,
+        )
+
+    evidence_path = attestation.get("evidence_path")
+    if evidence_path is not None:
+        resolved_evidence = project_path(root, evidence_path)
+        if resolved_evidence is None:
+            return failed(
+                f"expectation {expectation_id!r} evidence_path is unsafe",
+                code="expectation_evidence_path_unsafe",
+            ), {"class": "invalid", "expected_expectation_sha256": expected_hash}
+        if not resolved_evidence.is_file():
+            return warning(
+                f"expectation {expectation_id!r} evidence file is unavailable",
+                code="expectation_evidence_unavailable",
+            ), _evidence(
+                "stale_attestation",
+                attestation=attestation,
+                expected_expectation_hash=expected_hash,
+            )
+        if sha256_file(resolved_evidence) != normalized_evidence_hash:
+            return warning(
+                f"expectation {expectation_id!r} evidence file changed after review",
+                code="expectation_evidence_changed",
+            ), _evidence(
+                "stale_attestation",
+                attestation=attestation,
+                expected_expectation_hash=expected_hash,
+            )
+
+    checked_args, arg_error = _validate_args(root, check, args)
+    if arg_error is not None:
+        return arg_error, {
+            "class": "invalid",
+            "expected_expectation_sha256": expected_hash,
+        }
+    if checked_args is None:  # defensive: _validate_args returns one or the other
+        return failed("expectation args are invalid", code="expectation_args_invalid"), {
+            "class": "invalid",
+            "expected_expectation_sha256": expected_hash,
+        }
+
+    try:
+        result = EXPECTATION_CHECKS[check](root, **checked_args)
+    except Exception as exc:  # noqa: BLE001 - one expectation must not abort the report
+        result = not_testable(f"{type(exc).__name__}: {exc}", code="check_error")
+    evidence = _evidence(
+        "attested",
+        attestation=attestation,
+        expected_expectation_hash=expected_hash,
+    )
+    if result.status == "passed":
+        result = passed(f"attested expectation {expectation_id!r} satisfied: {result.detail}")
+    return result, evidence

openmapstack/integrity.py

@@ -0,0 +1,137 @@
+"""Canonical, path-aware hashing for OpenMapStack run evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import shlex
+from pathlib import Path
+from typing import Any, Iterable
+
+from .project import get_in, project_path
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return f"sha256:{digest.hexdigest()}"
+
+
+def normalize_digest(value: object) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    normalized = value.strip().lower()
+    if not normalized.startswith("sha256:"):
+        normalized = f"sha256:{normalized}"
+    payload = normalized.removeprefix("sha256:")
+    if len(payload) != 64 or any(char not in "0123456789abcdef" for char in payload):
+        return None
+    return normalized
+
+
+def canonical_file_set_hash(root: Path, paths: Iterable[str | Path]) -> str:
+    """Hash a sorted set of project-relative path names and file bytes.
+
+    Including the relative name prevents two differently named inventories
+    with identical concatenated contents from sharing a digest. Duplicate
+    paths are collapsed because an inventory represents a set of files.
+    """
+    digest = hashlib.sha256()
+    normalized = sorted({Path(path).as_posix() for path in paths})
+    for relative in normalized:
+        target = project_path(root, relative)
+        if target is None or not target.is_file():
+            raise ValueError(f"cannot hash missing or unsafe project file: {relative}")
+        encoded = relative.encode("utf-8")
+        digest.update(len(encoded).to_bytes(8, "big"))
+        digest.update(encoded)
+        with target.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                digest.update(chunk)
+    return f"sha256:{digest.hexdigest()}"
+
+
+def file_inventory(root: Path, paths: Iterable[str | Path]) -> list[dict[str, str]]:
+    normalized = sorted({Path(path).as_posix() for path in paths})
+    inventory: list[dict[str, str]] = []
+    for relative in normalized:
+        target = project_path(root, relative)
+        if target is None or not target.is_file():
+            raise ValueError(f"cannot inventory missing or unsafe project file: {relative}")
+        inventory.append({"path": relative, "sha256": sha256_file(target)})
+    return inventory
+
+
+def declared_output_paths(project: dict[str, Any]) -> list[str]:
+    outputs = project.get("outputs") or {}
+    if not isinstance(outputs, dict):
+        return []
+    return sorted(
+        {
+            Path(output["path"]).as_posix()
+            for output in outputs.values()
+            if isinstance(output, dict)
+            and isinstance(output.get("path"), str)
+            and output["path"].strip()
+        }
+    )
+
+
+def declared_input_paths(root: Path, project: dict[str, Any]) -> list[str]:
+    """Return the immutable inputs and canonical implementation files.
+
+    The manifest itself is deliberately excluded because it contains the
+    resulting digest. Sources, overrides, pipeline/command-local files, and
+    declared dependencies are the clean-rerun inputs defined by the spec.
+    """
+    # project_path() returns resolved paths, so every path compared below must be
+    # measured against a resolved root. On macOS the temp and /var trees are
+    # symlinks, so an unresolved root differs from a resolved child by a
+    # /private prefix and relative_to() raises.
+    resolved_root = root.resolve()
+    paths: set[str] = set()
+    for relative_dir in ("data/source", "data/overrides"):
+        directory = project_path(root, relative_dir)
+        if directory is not None and directory.is_dir():
+            paths.update(
+                path.relative_to(resolved_root).as_posix()
+                for path in directory.rglob("*")
+                if path.is_file()
+            )
+
+    implementation = get_in(project, "runtime", "implementation", default={})
+    if not isinstance(implementation, dict):
+        return sorted(paths)
+    pipeline = implementation.get("pipeline")
+    if isinstance(pipeline, str) and pipeline.strip():
+        paths.add(Path(pipeline).as_posix())
+    command = implementation.get("command")
+    if isinstance(command, str):
+        try:
+            tokens = shlex.split(command)
+        except ValueError:
+            tokens = []
+    else:
+        tokens = command if isinstance(command, list) else []
+    for token in tokens:
+        if not isinstance(token, str) or token.startswith("-"):
+            continue
+        target = project_path(root, token)
+        if target is not None and target.is_file():
+            paths.add(Path(token).as_posix())
+    for dependency in implementation.get("dependencies") or []:
+        if not isinstance(dependency, str):
+            continue
+        target = project_path(root, dependency)
+        if target is None:
+            continue
+        if target.is_file():
+            paths.add(Path(dependency).as_posix())
+        elif target.is_dir():
+            paths.update(
+                path.relative_to(resolved_root).as_posix()
+                for path in target.rglob("*")
+                if path.is_file()
+            )
+    return sorted(paths)

openmapstack/project.py

@@ -0,0 +1,79 @@
+"""Project loading and path helpers for ``openmapstack-project/v1``."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ProjectError(Exception):
+    """A project manifest cannot be loaded safely."""
+
+
+def resolve_project_file(value: str | Path) -> Path:
+    """Resolve a manifest argument, accepting either a file or project directory."""
+    path = Path(value).expanduser()
+    if path.is_dir():
+        path = path / "project.yaml"
+    return path.resolve()
+
+
+def load_project(value: str | Path) -> tuple[Path, dict[str, Any]]:
+    path = resolve_project_file(value)
+    if not path.is_file():
+        raise ProjectError(f"project manifest does not exist: {path}")
+    try:
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, yaml.YAMLError) as exc:
+        raise ProjectError(f"cannot parse {path}: {exc}") from exc
+    if not isinstance(loaded, dict):
+        raise ProjectError(f"project manifest must contain a YAML mapping: {path}")
+    return path, loaded
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ProjectError(f"cannot parse JSON file {path}: {exc}") from exc
+    if not isinstance(loaded, dict):
+        raise ProjectError(f"JSON document must contain an object: {path}")
+    return loaded
+
+
+def project_path(root: Path, value: object) -> Path | None:
+    """Resolve a project-relative path without allowing escape from the project."""
+    if not isinstance(value, str) or not value.strip():
+        return None
+    relative = Path(value)
+    if relative.is_absolute():
+        return None
+    target = (root / relative).resolve()
+    try:
+        target.relative_to(root.resolve())
+    except ValueError:
+        return None
+    return target
+
+
+def get_in(value: object, *keys: str, default: Any = None) -> Any:
+    current = value
+    for key in keys:
+        if not isinstance(current, dict) or key not in current:
+            return default
+        current = current[key]
+    return current
+
+
+def step_outputs(step: object) -> list[str]:
+    if not isinstance(step, dict):
+        return []
+    raw = step.get("output")
+    if isinstance(raw, str):
+        return [part.strip() for part in raw.split(",") if part.strip()]
+    if isinstance(raw, list):
+        return [str(item).strip() for item in raw if str(item).strip()]
+    return []