orchestrata_ultimate.factory.enforcement.attestation

Reference › orchestrata_ultimate › factory › enforcement › attestation

attestation maps a governed-write record into the vocabulary of external supply-chain verifiers (SPEC-033 section 7, row B20, ADR-0030). The models module shaped GovernedWriteRecord like in-toto link metadata but produced no real artefact; this module is the pure mapping into real in-toto link metadata and a SLSA provenance statement. It signs nothing; signing is in signing. InTotoLink holds a name, materials, products, byproducts and an environment. SlsaProvenance holds a builder id, a build type, an invocation and a SLSA level. link_from_record converts a record into a link, prefixing digests with sha256: (_digest), and provenance_for builds the provenance statement for a record and a builder id. DECLARED_SLSA_LEVEL is 1, the level the factory meets today, and the build type is an opaque versioned identifier rather than a network resource. canonical_json serialises either type deterministically (sorted keys, no whitespace, UTF-8), which is the form that gets signed. attestation_store imports it; tests are in tests/factory/test_attestation.py.

At a glance

Class diagram

Dependency diagram

API

Classes

InTotoLink (dataclass)

Decorators: dataclass(frozen=True) · Line 36

ITE-6-shaped in-toto link metadata (ADR-0030).

SlsaProvenance (dataclass)

Decorators: dataclass(frozen=True) · Line 95

SLSA provenance for one governed-write step (ADR-0030).

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/factory/enforcement/attestation.py

"""in-toto link + SLSA provenance mapping (ADR-0030, SPEC-033 §7, B20).

B1c (committed, ``models.py``) shaped ``GovernedWriteRecord`` like in-toto
link metadata but never produced a real in-toto/SLSA artefact. This module
is the pure mapping from that record into REAL in-toto link metadata and a
SLSA provenance statement -- the vocabulary an external in-toto/SLSA
verifier could actually consume, which is ADR-0030's whole point. No
signing happens here (see :mod:`.signing`); this module is data-shape only.
"""

from __future__ import annotations

import json
from dataclasses import asdict, dataclass, field

from orchestrata_ultimate.factory.enforcement.models import (
    DELETION_MARKER,
    GovernedWriteRecord,
)

_SHA256_PREFIX = "sha256:"


def _digest(value: str) -> str:
    """Prefix a bare hex digest with ``sha256:`` per the in-toto link
    vocabulary -- except the B1a deletion sentinel (:data:`DELETION_MARKER`),
    which is not a digest at all and is passed through verbatim so a
    verifier never mistakes a declared deletion for a (nonsensical) hash of
    the literal word "deleted"."""
    if value == DELETION_MARKER:
        return value
    return f"{_SHA256_PREFIX}{value}"


@dataclass(frozen=True)
class InTotoLink:
    """ITE-6-shaped in-toto link metadata (ADR-0030).

    Field names (``name``, ``materials``, ``products``, ``byproducts``,
    ``environment``) match the in-toto link vocabulary so an external
    in-toto verifier can consume this shape directly. ``environment``
    carries the ADR-0001/ADR-0004 ``(worktree, commit)`` correlation key --
    in-toto's ``environment`` field is free-form step context, and this is
    ours (:meth:`AttestationStore.attestations_for` filters on it).
    """

    name: str
    materials: dict[str, str]
    products: dict[str, str]
    byproducts: dict[str, str] = field(default_factory=dict)
    environment: dict[str, str] = field(default_factory=dict)


def link_from_record(record: GovernedWriteRecord) -> InTotoLink:
    """Pure mapping: a ``GovernedWriteRecord`` -> in-toto link metadata.

    The writer's name becomes the step ``name``; material/product hashes
    become ``sha256:``-prefixed digests (the B1a deletion sentinel is left
    verbatim, see :func:`_digest`); ``byproducts`` carries over unchanged
    (free-form metadata such as an exit code, not a hash); ``environment``
    carries the ``(worktree, commit)`` correlation key.
    """
    return InTotoLink(
        name=record.writer.name,
        materials={path: _digest(h) for path, h in record.materials.items()},
        products={path: _digest(h) for path, h in record.products.items()},
        byproducts=dict(record.byproducts),
        environment={"worktree": record.worktree, "commit": record.commit},
    )


def canonical_json(obj: InTotoLink | SlsaProvenance) -> bytes:
    """Deterministic serialization: sorted keys, no whitespace, UTF-8.

    This is the exact byte string that gets signed (see
    ``attestation_store._signing_payload``) -- it must round-trip stably:
    the same link or provenance produces the same bytes every time,
    regardless of field-insertion order.
    """
    return json.dumps(asdict(obj), sort_keys=True, separators=(",", ":")).encode(
        "utf-8"
    )


# The SLSA level this factory ACTUALLY meets today. See `SlsaProvenance`'s
# docstring for why L2/L3 are not (yet) claimed.
DECLARED_SLSA_LEVEL = 1

# SLSA build-type identifier for a governed-write step. Not a network
# resource -- an opaque, versioned identifier per the SLSA provenance spec.
_BUILD_TYPE = "https://orchestrata.dev/factory/governed-write@v1"


@dataclass(frozen=True)
class SlsaProvenance:
    """SLSA provenance for one governed-write step (ADR-0030).

    Honesty about the level (Phase 1, B20): this provenance is generated by
    the platform -- the trusted attestation CLI/gate (``scripts/
    factory_enforce.py attest``) -- never by the agent whose write it
    describes. That no-self-report property (ADR-0008/ADR-0030) is exactly
    the SLSA L1 bar, and it is what we meet. We do NOT yet have hermetic,
    isolated, or reproducible builds (that is B1d / a future phase), so
    SLSA L2 ("hosted build platform") and L3 ("hardened build platform,
    non-falsifiable provenance") are explicitly NOT claimed.
    ``slsa_level`` is always :data:`DECLARED_SLSA_LEVEL` -- callers must not
    construct a provenance claiming a different level than this module
    declares.
    """

    builder_id: str
    build_type: str
    invocation: dict
    slsa_level: int


def provenance_for(record: GovernedWriteRecord, builder_id: str) -> SlsaProvenance:
    """Build the SLSA provenance statement for one governed-write record.

    ``builder_id`` identifies the trusted platform/gate that generated this
    provenance -- it must be a builder/platform identity, never the agent
    identity being governed (no-self-report, ADR-0008/ADR-0030); callers
    are responsible for passing the correct one.
    """
    return SlsaProvenance(
        builder_id=builder_id,
        build_type=_BUILD_TYPE,
        invocation={
            "record_id": record.record_id,
            "writer": record.writer.name,
            "worktree": record.worktree,
            "commit": record.commit,
        },
        slsa_level=DECLARED_SLSA_LEVEL,
    )