orchestrata_ultimate.factory.enforcement.signing

Reference › orchestrata_ultimate › factory › enforcement › signing

signing provides the signing seam for attestations (SPEC-033 section 7, row B20, ADR-0030). Signer is a runtime-checkable protocol with a key_id property, sign(payload) returning a hex signature and verify(payload, signature) returning a boolean. HmacSigner is the Phase-1 implementation: HMAC-SHA256 over key material read from a key file, with a stable key_id that is safe to store alongside signatures. ensure_key_file creates the key file with fresh random material when it does not exist. The module proves the attestation flow of sign, store and verify, and detection of tampering, and it makes no claim beyond what it implements. attestation_store and the scripts.factory_enforce CLI import it; tests are in tests/factory/test_attestation_store.py.

At a glance

Class diagram

Dependency diagram

API

Classes

Signer (protocol)

Bases: Protocol · Decorators: runtime_checkable · Line 23

The signing/verification surface an attestation store depends on.

HmacSigner

Line 42

Phase-1 :class:Signer: HMAC-SHA256 over a symmetric key file.

Functions

Source

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

"""Attestation signing (ADR-0030, SPEC-033 §7, B20).

# Phase-1 signer: HMAC-SHA256 (symmetric). ADR-0030's target is asymmetric
# (in-toto uses ed25519/RSA); asymmetric signing + a real key-management
# story is the B20-followup, gated on choosing a KMS. HMAC proves the
# ATTESTATION FLOW end to end (sign -> store -> verify, tamper-detected)
# without pulling a crypto dependency before the key-management decision is
# made. This is the honest seam, not a shortcut hidden: no code here claims
# asymmetric signing, and ``SlsaProvenance``/CLI output never overclaims it
# either.
"""

from __future__ import annotations

import hashlib
import hmac
import os
from pathlib import Path
from typing import Protocol, runtime_checkable


@runtime_checkable
class Signer(Protocol):
    """The signing/verification surface an attestation store depends on."""

    @property
    def key_id(self) -> str:
        """A stable identifier for the key material, safe to store
        alongside a signature (never the key itself)."""
        ...

    def sign(self, payload: bytes) -> str:
        """Return a hex signature over ``payload``."""
        ...

    def verify(self, payload: bytes, signature: str) -> bool:
        """Return whether ``signature`` is a valid signature of
        ``payload`` under this signer's key."""
        ...


class HmacSigner:
    """Phase-1 :class:`Signer`: HMAC-SHA256 over a symmetric key file.

    See the module docstring for why this is HMAC rather than asymmetric
    signing. ``key_id`` is derived from the key material itself (sha256 of
    its first 8 bytes) so distinct keys get distinct ids deterministically,
    without ever exposing the key.
    """

    def __init__(self, key_path: Path):
        self._key_path = Path(key_path)
        self._key = self._key_path.read_bytes()
        self._key_id = hashlib.sha256(self._key[:8]).hexdigest()

    @property
    def key_id(self) -> str:
        """This signer's stable key identifier (see the class docstring)."""
        return self._key_id

    def sign(self, payload: bytes) -> str:
        """Return the hex HMAC-SHA256 signature of ``payload``."""
        return hmac.new(self._key, payload, hashlib.sha256).hexdigest()

    def verify(self, payload: bytes, signature: str) -> bool:
        """Return whether ``signature`` is this signer's HMAC-SHA256 of
        ``payload`` (constant-time comparison)."""
        expected = self.sign(payload)
        return hmac.compare_digest(expected, signature)


def ensure_key_file(key_path: Path) -> Path:
    """Create ``key_path`` with fresh random key material if it does not
    already exist; return it either way.

    Library-side helper used by the CLI (which alone resolves
    ``FACTORY_ATTEST_KEY_PATH`` from the environment, per project rules) so
    a first-run ``attest`` invocation does not require a manual
    key-generation step. Idempotent: a second call against an existing key
    file is a no-op (the key is never regenerated once it exists, since
    that would invalidate every attestation already signed with it).
    """
    key_path = Path(key_path)
    if not key_path.exists():
        key_path.parent.mkdir(parents=True, exist_ok=True)
        key_path.write_bytes(os.urandom(32))
    return key_path