techtree 0.1.0__py3-none-any.whl

techtree/fs.py

@@ -0,0 +1,234 @@
+"""Safe filesystem primitives. Spec section 10.9.
+
+Two properties matter here and both are about what a reader can observe.
+
+*Atomicity.* A reader must never see a half-written file. Writes go to a
+temporary file in the same directory, are flushed and fsynced, and then replace
+the target with ``os.replace``, which is atomic within a filesystem. The
+containing directory is fsynced afterwards so the rename itself survives a
+crash.
+
+*Immutability.* Campaign, Climb, DataPolicy, manifest, lock, and receipt
+artifacts are written exactly once. :func:`open_exclusive` creates them with
+``O_EXCL``, so a second attempt to write one is reported as a conflict instead
+of quietly replacing evidence.
+
+*Privacy.* Techtree state is single-user: files are ``0600`` and directories
+``0700``. Both helpers that create a directory create *every* directory they
+need at that mode, because a private leaf at the end of a world-readable path
+is not private — a run directory nobody can list is still a run directory
+whose parent tells you it exists.
+
+Nothing here follows symlinks into a location the caller did not name.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+from typing import BinaryIO, cast
+
+from techtree.canonical import to_json_value
+from techtree.errors import ConflictError, NotFoundError, ValidationError
+from techtree.models.base import JsonValue
+
+__all__ = [
+    "atomic_write_bytes",
+    "atomic_write_json",
+    "atomic_write_text",
+    "ensure_private_directory",
+    "fsync_directory",
+    "open_exclusive",
+    "read_json",
+    "realpath_within",
+    "remove_tree",
+]
+
+#: Owner read and write only. Techtree state is single-user by design.
+_FILE_MODE = 0o600
+#: Owner traversal only, so a run directory is not world-readable.
+_DIRECTORY_MODE = 0o700
+
+
+def _make_private_directory(path: Path) -> None:
+    """Create a directory and every missing parent, each one private.
+
+    ``mkdir(parents=True)`` creates the intermediate directories under the
+    process umask and leaves them there, so hardening only the leaf hardens
+    the room and not the corridor. Inside a Techtree home every ancestor
+    happens to be ``0700`` already, which made this a latent defect rather
+    than a live leak — and the distance between those two is one caller
+    passing a path whose parent does not exist yet.
+
+    The mode is applied at creation rather than after it, so there is no
+    instant in which the directory exists and anyone else can read it. A
+    umask can only take bits away from that mode, never add them, and the
+    ``chmod`` afterwards makes the result exact on a machine whose umask is
+    unusual.
+
+    Only directories this call creates are touched. A directory that was
+    already there belongs to whoever made it, and quietly tightening
+    somebody's home directory to ``0700`` would be a worse bug than the one
+    being fixed here.
+    """
+    missing: list[Path] = []
+    current = path
+    while not current.is_dir():
+        missing.append(current)
+        if current.parent == current:
+            break
+        current = current.parent
+
+    for directory in reversed(missing):
+        try:
+            directory.mkdir(mode=_DIRECTORY_MODE)
+        except FileExistsError:
+            if directory.is_dir():
+                # Another process created it between the walk and here. It is
+                # a Techtree directory either way, made by this same code.
+                continue
+            # The path exists and is not a directory, which is what the
+            # caller needs to hear about.
+            raise
+        # Windows and some network filesystems have no POSIX mode bits. The
+        # directory still exists, which is what the caller asked for.
+        with suppress(NotImplementedError, OSError):
+            os.chmod(directory, _DIRECTORY_MODE)
+
+
+def atomic_write_bytes(path: Path, data: bytes, *, mode: int = _FILE_MODE) -> None:
+    """Write, fsync, chmod, and atomically replace."""
+    directory = path.parent
+    _make_private_directory(directory)
+
+    handle, temporary_name = tempfile.mkstemp(
+        dir=directory, prefix=f".{path.name}.", suffix=".tmp"
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(handle, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+    fsync_directory(directory)
+
+
+def atomic_write_text(path: Path, text: str, *, mode: int = _FILE_MODE) -> None:
+    """UTF-8 wrapper."""
+    atomic_write_bytes(path, text.encode("utf-8"), mode=mode)
+
+
+def atomic_write_json(path: Path, value: object, *, mode: int = _FILE_MODE) -> None:
+    """Write readable JSON atomically.
+
+    This is the human-readable spelling, indented and newline-terminated. It is
+    not the canonical spelling; anything that is going to be hashed is
+    serialized with :func:`techtree.canonical.canonical_json_bytes`.
+    """
+    rendered = json.dumps(
+        to_json_value(value),
+        indent=2,
+        sort_keys=True,
+        ensure_ascii=False,
+    )
+    atomic_write_text(path, f"{rendered}\n", mode=mode)
+
+
+def read_json(path: Path) -> JsonValue:
+    """Read UTF-8 JSON and raise typed malformed-data errors."""
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError as error:
+        raise NotFoundError(
+            f"no such file: {path}",
+            details={"path": str(path)},
+        ) from error
+
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise ValidationError(
+            f"file is not valid UTF-8: {path}",
+            details={"path": str(path)},
+        ) from error
+
+    try:
+        return cast(JsonValue, json.loads(text))
+    except json.JSONDecodeError as error:
+        raise ValidationError(
+            f"file is not valid JSON: {path} ({error.msg} at line {error.lineno})",
+            details={"path": str(path), "line": error.lineno},
+        ) from error
+
+
+def ensure_private_directory(path: Path) -> None:
+    """Create a directory, and every parent it needs, 0700 where supported."""
+    if path.is_symlink():
+        raise ValidationError(
+            f"refusing to use a symlinked directory: {path}",
+            details={"path": str(path)},
+        )
+    _make_private_directory(path)
+    # An existing directory is re-hardened, because this function's promise to
+    # its caller is about the directory it returns, not only about the case
+    # where it had to make one.
+    with suppress(NotImplementedError, OSError):
+        os.chmod(path, _DIRECTORY_MODE)
+
+
+def fsync_directory(path: Path) -> None:
+    """Best-effort directory fsync."""
+    try:
+        descriptor = os.open(path, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(descriptor)
+    except OSError:
+        # Directory fsync is unsupported on some platforms and filesystems.
+        pass
+    finally:
+        os.close(descriptor)
+
+
+def remove_tree(path: Path) -> None:
+    """Remove run-owned data without following links."""
+    if path.is_symlink():
+        # Unlink the link itself; never descend into whatever it points at.
+        path.unlink()
+        return
+    if not path.exists():
+        return
+    if path.is_dir():
+        shutil.rmtree(path)
+        return
+    path.unlink()
+
+
+def realpath_within(path: Path, root: Path) -> bool:
+    """Return whether a resolved path is contained in root."""
+    return path.resolve().is_relative_to(root.resolve())
+
+
+def open_exclusive(path: Path, mode: int = _FILE_MODE) -> BinaryIO:
+    """Create an immutable file with O_EXCL semantics."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    try:
+        descriptor = os.open(path, flags, mode)
+    except FileExistsError as error:
+        raise ConflictError(
+            f"refusing to overwrite an immutable artifact: {path}",
+            details={"path": str(path)},
+        ) from error
+    return cast(BinaryIO, os.fdopen(descriptor, "wb"))

techtree/harness.py

@@ -0,0 +1,108 @@
+"""The tool surface a pinned harness offers. Decisions 0007 R9 item 4.
+
+Mounting a Skill changes what the subject is offered. Hermes 0.19.0 renders the
+index of visible Skills into the description of its own Skill-management tool,
+so the candidate variant is handed one tool description the baseline was not,
+and a comparison that demanded one identical tool surface would reject every
+correct run.
+
+That leaves a question a comparison cannot answer from the run alone: is a
+description difference *the* expected one, or is it evidence that the harness
+pin moved underneath the Campaign? Both look the same from inside a single
+comparison — one description differing on one tool.
+
+This module holds the other half of the answer: a conformance fixture recording
+the tool surface the pinned harness offers, tool by tool, schema by schema. The
+ratified rule (decisions document 0007, release ratifications) is an exact
+derived difference — the tool count, the tool names, the parameter schemas and
+the capabilities are unchanged, and only the known skill-aware description field
+differs. Everything in that sentence except the description is pinned here, so a
+future harness that adds a tool, drops one, renames one or reshapes a schema
+fails the comparison instead of being absorbed into "the Skill index changed".
+
+Descriptions are deliberately *not* pinned. A description holds the names of the
+Skills currently mounted, so its digest is a property of the Campaign's Skill
+rather than of the harness, and pinning it would make the fixture wrong the
+first time a different Skill was measured.
+
+The fixture is recorded from real evaluations, never authored. Each file says
+which ones in its own ``recorded_from`` field.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+from typing import Final
+
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel
+
+__all__ = [
+    "HARNESS_CONFORMANCE_SCHEMA_VERSION",
+    "ConformanceTool",
+    "HarnessConformance",
+    "harness_conformance",
+]
+
+#: The schema every conformance fixture declares.
+HARNESS_CONFORMANCE_SCHEMA_VERSION: Final = "techtree.harness-conformance.v1alpha1"
+
+_RESOURCE_DIRECTORY: Final = "harness"
+
+
+class ConformanceTool(ProtocolModel):
+    """One tool the pinned harness offers, by name and parameter schema."""
+
+    name: NonEmptyString
+    parameters_digest: Digest
+
+
+class HarnessConformance(ProtocolModel):
+    """The tool surface one pinned harness build offers."""
+
+    schema_version: NonEmptyString
+    harness_id: NonEmptyString
+    harness_version: NonEmptyString
+    skill_index_tool: NonEmptyString
+    recorded_from: NonEmptyString
+    tools: list[ConformanceTool]
+
+    @property
+    def tool_names(self) -> list[str]:
+        """Every tool name, in the order the fixture records them."""
+        return [tool.name for tool in self.tools]
+
+    @property
+    def parameters_by_tool(self) -> dict[str, Digest]:
+        """Each tool's parameter-schema digest, by tool name."""
+        return {tool.name: tool.parameters_digest for tool in self.tools}
+
+
+@cache
+def harness_conformance(harness_id: str, harness_version: str) -> HarnessConformance:
+    """Load the conformance fixture for one pinned harness build.
+
+    Raises :class:`FileNotFoundError` when no fixture was ever recorded for that
+    build, which is the correct outcome: a harness nobody measured has no
+    expected tool surface, and inventing one would be the opposite of a
+    conformance fixture.
+    """
+    resource = (
+        resources.files("techtree")
+        / "resources"
+        / _RESOURCE_DIRECTORY
+        / f"{harness_id}-{harness_version}.json"
+    )
+    if not resource.is_file():
+        raise FileNotFoundError(
+            f"no tool surface was recorded for {harness_id} {harness_version}"
+        )
+    document = json.loads(resource.read_text(encoding="utf-8"))
+    conformance = HarnessConformance.model_validate(document)
+    if conformance.schema_version != HARNESS_CONFORMANCE_SCHEMA_VERSION:
+        raise ValueError(
+            f"{resource} declares {conformance.schema_version}, not "
+            f"{HARNESS_CONFORMANCE_SCHEMA_VERSION}"
+        )
+    return conformance

techtree/identity/__init__.py

@@ -0,0 +1,41 @@
+"""The one local key that binds a participant to their own receipts.
+
+Spec section 7.5. Decisions document 0005, amendment 4.
+
+WP0 built the Ed25519 primitives and froze them shut: :mod:`techtree.crypto`
+knows how to make a key and check a signature, and nothing in the package knew
+where a key lived or when to use one. This package is the activation, and it is
+deliberately the *whole* of it — every other module asks this one to sign, so
+there is exactly one place that touches private material.
+
+Three rules hold everywhere below.
+
+*The private half never leaves the identities directory.* It is written once,
+owner-readable only, and loaded into memory to sign a digest. It is never
+serialized into a document, never logged, never carried in a typed error's
+details, and never written into a proof bundle. Only the public half travels.
+
+*The key is self-issued, and the vocabulary says so.* Nothing registers it,
+nothing uploads it, and no authority vouches for it. What a signature over
+these receipts proves is that the participant's own key vouches for bytes that
+verify against each other — which is what ``proof_grade: P1`` is permitted to
+mean and nothing more.
+
+*What is signed is the digest string.* :func:`techtree.crypto.sign_digest`
+signs the ASCII ``sha256:...`` spelling of the canonical bytes, so a verifier
+holding the digest can check the signature, and the thing attested to is
+exactly the value that appears in the protocol document.
+
+The division of labour:
+
+``models``
+    The public identity, and the shape a verification verdict is reported in.
+``store``
+    Where the key material lives on disk, and how it is created and loaded.
+``service``
+    Signing objects into envelopes, and verifying envelopes against a key.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

techtree/identity/models.py

@@ -0,0 +1,113 @@
+"""The local identity, and the shape of a verification verdict.
+
+Spec sections 7.5 and 7.12.
+
+Two vocabularies live here because they are used together everywhere and
+neither one belongs to the frozen v0.1 protocol.
+
+:class:`ExecutorIdentity` is the public half of the participant's key, written
+into the identities directory and copied into every proof bundle. It is a
+:class:`~techtree.models.base.ProtocolModel` so that it is frozen, canonically
+serializable, and digestible like everything else a bundle commits to. The
+private half has no model at all: it is raw bytes on disk and an in-memory key
+object, and giving it a document shape would be the first step towards it
+appearing in one.
+
+:class:`VerificationResult` is how every check in this subsystem reports. A
+verifier that raised on the first broken thing would tell a reader which rule
+failed first rather than what is wrong with what they are holding, so checks
+are collected: each one named, each one with its own stable code, and the
+verdict computed from them rather than asserted alongside them.
+"""
+
+from __future__ import annotations
+
+from typing import Final, Literal, Self
+
+from pydantic import model_validator
+
+from techtree.models.base import (
+    Base64String,
+    NonEmptyString,
+    ProtocolModel,
+    UtcDateTime,
+)
+
+__all__ = [
+    "LOCAL_IDENTITY_INVALID",
+    "SIGNATURE_VERIFICATION_FAILED",
+    "ExecutorIdentity",
+    "VerificationMessage",
+    "VerificationResult",
+    "VerificationStatus",
+]
+
+type VerificationStatus = Literal["passed", "failed", "warning"]
+"""What one check found. ``warning`` is a claim that holds more weakly than it
+wanted to, never a failure that someone decided to be relaxed about."""
+
+#: Stable error codes. Spec section 15.
+LOCAL_IDENTITY_INVALID: Final = "local_identity_invalid"
+SIGNATURE_VERIFICATION_FAILED: Final = "signature_verification_failed"
+
+
+class ExecutorIdentity(ProtocolModel):
+    """The public half of one participant-controlled local signing key.
+
+    ``created_at`` is operational identity metadata: it says when this machine
+    made a key, and it is deliberately not part of any scientific comparison.
+    Two participants running the same Campaign produce the same measurements
+    and different identities.
+    """
+
+    kind: Literal["local_ed25519"]
+    key_id: NonEmptyString
+    algorithm: Literal["ed25519"]
+    public_key: Base64String
+    created_at: UtcDateTime
+
+
+class VerificationMessage(ProtocolModel):
+    """One named check and what it found.
+
+    ``code`` is the spec section 15 error code a failure of this check reports
+    under, so a machine reading a failed verification gets the same vocabulary
+    whether it read the envelope or the exception.
+    """
+
+    id: NonEmptyString
+    status: VerificationStatus
+    code: NonEmptyString
+    detail: NonEmptyString
+
+
+class VerificationResult(ProtocolModel):
+    """Every check a verification ran, and whether the thing verified."""
+
+    verified: bool
+    messages: list[VerificationMessage]
+
+    @property
+    def failures(self) -> list[VerificationMessage]:
+        """Return every check that failed."""
+        return [message for message in self.messages if message.status == "failed"]
+
+    @property
+    def warnings(self) -> list[VerificationMessage]:
+        """Return every check that passed with a weaker claim than it wanted."""
+        return [message for message in self.messages if message.status == "warning"]
+
+    @model_validator(mode="after")
+    def _check_the_verdict_is_the_one_the_checks_support(self) -> Self:
+        """Reject a result whose verdict disagrees with its own checks."""
+        if self.verified and self.failures:
+            raise ValueError(
+                "a verification that reports success cannot carry a failed check"
+            )
+        if not self.verified and not self.failures:
+            raise ValueError(
+                "a verification that reports failure must name the check that failed"
+            )
+        if not self.messages:
+            raise ValueError("a verification result records the checks it ran")
+        return self

techtree/identity/service.py

@@ -0,0 +1,199 @@
+"""Signing objects, and checking signed ones. Spec sections 7.5 and 7.12.
+
+Everything that gets signed in Techtree goes through :meth:`IdentityService.
+sign_object`, and everything that gets checked goes through
+:func:`verify_signed_object`. Keeping both on one page is what makes the two
+halves impossible to drift apart: the signature is made over the digest of the
+payload's canonical bytes, and the check recomputes that digest from the
+payload it was handed rather than trusting the one the envelope records.
+
+That recomputation is the entire point of the envelope. A stored envelope
+carries ``payload_digest`` and never recalculates it during validation, so an
+edited payload keeps its old digest and looks fine to a parser. Verification is
+where the two are compared, and it is why a receipt that was changed after it
+was written cannot pass.
+
+Verification takes the identity it should check against as an argument rather
+than reading the local store. A proof bundle carries the public key that signed
+it, and a bundle is verified against *that* key — offline, on another machine,
+with no Techtree identity of its own. Checking a stranger's bundle against this
+machine's key would fail every bundle for the wrong reason.
+
+What a verified signature proves is bounded and worth stating plainly: these
+bytes have not changed since the holder of that private key signed them. The
+key is self-issued and local, so nothing here says who ran the evaluation, and
+nothing here is a third party's word for anything.
+"""
+
+from __future__ import annotations
+
+from base64 import b64decode
+from typing import Final
+
+from pydantic import BaseModel
+
+from techtree.canonical import digest_object
+from techtree.crypto import load_public_key, sign_digest, verify_signature
+from techtree.errors import ValidationError
+from techtree.identity.models import (
+    LOCAL_IDENTITY_INVALID,
+    SIGNATURE_VERIFICATION_FAILED,
+    ExecutorIdentity,
+    VerificationMessage,
+    VerificationResult,
+)
+from techtree.identity.store import IdentityStore
+from techtree.models.base import ObjectEnvelope
+
+__all__ = [
+    "IdentityService",
+    "verify_signed_object",
+]
+
+_PASSED: Final = "passed"
+_FAILED: Final = "failed"
+
+
+class IdentityService:
+    """The local identity, ready to sign and to check its own signatures."""
+
+    def __init__(self, store: IdentityStore) -> None:
+        self._store = store
+
+    @property
+    def store(self) -> IdentityStore:
+        """Return the store this service signs with."""
+        return self._store
+
+    def ensure(self) -> ExecutorIdentity:
+        """Return the existing valid identity, creating one if there is none.
+
+        Creation happens when a person has asked for something that needs a
+        key — ``techtree setup``, or a run they started reaching the point
+        where its receipts are sealed. Nothing creates a key at import time and
+        nothing creates one on a machine that is only being inspected.
+
+        An identity whose two halves no longer describe each other is not
+        silently replaced. The old key signed real receipts; replacing it would
+        make those signatures unverifiable without saying so.
+        """
+        if not self._store.exists():
+            return self._store.create()
+
+        identity = self._store.load_public()
+        if self._store.verify_pair():
+            return identity
+        raise ValidationError(
+            "the two halves of this machine's local signing identity do not "
+            "describe the same key, so nothing may be signed with it",
+            code=LOCAL_IDENTITY_INVALID,
+            details={"key_id": identity.key_id},
+        )
+
+    def sign_object[T: BaseModel](self, value: T) -> ObjectEnvelope[T]:
+        """Canonicalize, digest, and sign one protocol object."""
+        identity = self._store.load_public()
+        digest = digest_object(value)
+        signature = sign_digest(
+            self._store.load_private(), digest, key_id=identity.key_id
+        )
+        return ObjectEnvelope[T](
+            payload=value, payload_digest=digest, signature=signature
+        )
+
+    def verify_envelope[T: BaseModel](
+        self, envelope: ObjectEnvelope[T]
+    ) -> VerificationResult:
+        """Verify one envelope against this machine's own public identity."""
+        return verify_signed_object(
+            identity=self._store.load_public(), envelope=envelope
+        )
+
+
+def verify_signed_object[T: BaseModel](
+    *,
+    identity: ExecutorIdentity,
+    envelope: ObjectEnvelope[T],
+    subject: str = "object",
+) -> VerificationResult:
+    """Verify one envelope's digest and signature against a public identity.
+
+    ``subject`` names what is being checked — a bundle path, usually — so that
+    a reader of a failed bundle verification learns which of forty receipts is
+    the problem rather than that "a signature" failed.
+    """
+    messages: list[VerificationMessage] = []
+
+    computed = digest_object(envelope.payload)
+    digest_matches = computed == envelope.payload_digest
+    messages.append(
+        VerificationMessage(
+            id=f"{subject}.payload_digest",
+            status=_PASSED if digest_matches else _FAILED,
+            code=SIGNATURE_VERIFICATION_FAILED,
+            detail=(
+                "the payload still matches the digest it was signed under"
+                if digest_matches
+                else (
+                    "the payload no longer matches the digest it was signed "
+                    f"under: sealed {envelope.payload_digest}, computed {computed}"
+                )
+            ),
+        )
+    )
+
+    signature = envelope.signature
+    if signature is None:
+        messages.append(
+            VerificationMessage(
+                id=f"{subject}.signature_present",
+                status=_FAILED,
+                code=SIGNATURE_VERIFICATION_FAILED,
+                detail="this object carries no signature, so nothing vouches for it",
+            )
+        )
+        return VerificationResult(verified=False, messages=messages)
+
+    named_key = signature.key_id == identity.key_id
+    messages.append(
+        VerificationMessage(
+            id=f"{subject}.signature_key",
+            status=_PASSED if named_key else _FAILED,
+            code=LOCAL_IDENTITY_INVALID,
+            detail=(
+                f"signed by key {identity.key_id}"
+                if named_key
+                else (
+                    f"signed by key {signature.key_id}, which is not the key "
+                    f"{identity.key_id} this proof carries"
+                )
+            ),
+        )
+    )
+
+    verified = named_key and digest_matches and _signature_verifies(identity, envelope)
+    messages.append(
+        VerificationMessage(
+            id=f"{subject}.signature",
+            status=_PASSED if verified else _FAILED,
+            code=SIGNATURE_VERIFICATION_FAILED,
+            detail=(
+                "the signature verifies against the public key carried with it"
+                if verified
+                else "the signature does not verify against the public key "
+                "carried with it"
+            ),
+        )
+    )
+    return VerificationResult(verified=verified, messages=messages)
+
+
+def _signature_verifies[T: BaseModel](
+    identity: ExecutorIdentity, envelope: ObjectEnvelope[T]
+) -> bool:
+    """Check the detached signature against the identity's public key."""
+    signature = envelope.signature
+    if signature is None:
+        return False
+    public_key = load_public_key(b64decode(identity.public_key, validate=True))
+    return verify_signature(public_key, envelope.payload_digest, signature)