quantbom 0.6.0__py3-none-any.whl

quantbom/_sign.py

@@ -0,0 +1,284 @@
+"""Producer signing from a pip install (hybrid signing model, step 2 — MVP_PLAN.md B1).
+
+The producer's signature is the certificate's authorship claim: the releasing
+organisation signed its own evidence with its own key. Until now that needed the
+repository's `sign_evidence.py`; this module is the same construction in the
+wheel — Ed25519 over an in-toto Statement in a DSSE envelope, the subjects being
+the evidence artifacts the QBOM references, bound by SHA-256 — so a bundle
+signed here verifies in the gate's `sign_evidence.verify`, byte for byte.
+
+    quantbom keygen                      # ~/.quantbom/signing.key (0600) + signing.pub
+    quantbom sign --bundle bundle/       # evidence/attestation.json, signing properties
+    quantbom certify ... --sign          # collect, sign, certify in one go
+
+Needs `cryptography` (pip install "quantbom[signing]"); the core wheel stays
+stdlib-only, so the import is lazy and the error says what to install.
+
+Kept deliberately identical to sign_evidence.py where the bytes matter
+(PAYLOAD_TYPE, PREDICATE_TYPE, the PAE, the subject order, the key id). The
+`builder.id` differs ("secqdevops/quantbom-sdk") so an attestation says which
+tool made it; the verifier does not read it.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import stat
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+PAYLOAD_TYPE = "application/vnd.in-toto+json"
+PREDICATE_TYPE = "https://secqdevops/qbom-evidence/v0.1"
+BUILDER_ID = "secqdevops/quantbom-sdk"
+ROLE = "producer"
+
+# Artifact refs whose bytes become attestation subjects — the gate's list
+# (sign_evidence.SUBJECT_REF_PROPS); tests/harness/test_sdk_sign.py pins the two equal.
+SUBJECT_REF_PROPS = [
+    "secqdevops:circuit-artifact-ref",
+    "secqdevops:transpiled-circuit-ref",
+    "secqdevops:qasm-program-ref",
+    "secqdevops:native-program-ref",
+    "secqdevops:qir-program-ref",
+    "secqdevops:benchmark-ref",
+    "secqdevops:equivalence-ref",
+    "secqdevops:expected-distribution-ref",
+    "secqdevops:calibration-ref",
+    "secqdevops:provenance-artifact-ref",
+    "secqdevops:ct-proof-ref",
+    "secqdevops:vex-ref",
+    "secqdevops:cvd-policy-ref",
+    "secqdevops:test-report-ref",
+]
+
+# The producer's properties and files; a service countersignature uses its own
+# (service-*) and is never touched here.
+SIGNING_PROPERTY_NAMES = {
+    "secqdevops:signature-ref",
+    "secqdevops:signing-pubkey-ref",
+    "secqdevops:signing-key-id",
+    "secqdevops:attestation-sha256",
+}
+ATTESTATION_REL = "evidence/attestation.json"
+PUBKEY_REL = "evidence/signing.pub"
+
+# Where `quantbom keygen` puts the key and where `--sign` looks for it when no
+# path is given: the env var, then the user's home. Never the bundle, never
+# the project directory — a private key must not travel with the evidence.
+KEY_ENV = "QUANTBOM_SIGNING_KEY"
+DEFAULT_KEY_DIR = Path.home() / ".quantbom"
+LEGACY_KEY_DIR = Path.home() / ".zentroq"  # before the rename (0.6.0); read, never written
+PRIVATE_KEY_NAME = "signing.key"
+PUBLIC_KEY_NAME = "signing.pub"
+
+
+class SigningUnavailable(RuntimeError):
+    """`cryptography` is not installed."""
+
+
+def _load_crypto():
+    try:
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+    except ImportError as exc:  # the one dependency signing needs
+        raise SigningUnavailable('signing needs the cryptography package: pip install "quantbom[signing]"') from exc
+    return serialization, Ed25519PrivateKey
+
+
+def _canonical(data: Any) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("utf-8")
+
+
+def _sha256(raw: bytes) -> str:
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _pae(payload: bytes) -> bytes:
+    """DSSE Pre-Authentication Encoding over the payload."""
+    pt = PAYLOAD_TYPE.encode("utf-8")
+    return b"DSSEv1 " + str(len(pt)).encode() + b" " + pt + b" " + str(len(payload)).encode() + b" " + payload
+
+
+def key_id(public_key_raw: bytes) -> str:
+    """sha256 of the raw 32-byte public key, as /v1/keys and the gate compute it."""
+    return "sha256:" + _sha256(public_key_raw)
+
+
+def _write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def release_identity(sbom: dict[str, Any]) -> str:
+    """The release id a QBOM describes: `name@version` from metadata.component.
+
+    QBOMs before SDK 0.5.3 named the component `quantum-workload-<release_id>`
+    with a placeholder version; for those the name alone is the identity, as it
+    always was.
+    """
+    component = (sbom.get("metadata") or {}).get("component") or {}
+    name = component.get("name") or "unknown"
+    version = component.get("version")
+    if name.startswith("quantum-workload-") or not version:
+        return name
+    return f"{name}@{version}"
+
+
+def _properties(sbom: dict[str, Any]) -> dict[str, str]:
+    return {str(p["name"]): str(p["value"]) for p in sbom.get("metadata", {}).get("properties", [])
+            if p.get("name") and p.get("value") is not None}
+
+
+def _public_raw(private) -> bytes:
+    serialization, _ = _load_crypto()
+    return private.public_key().public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw)
+
+
+def _public_pem(private) -> bytes:
+    serialization, _ = _load_crypto()
+    return private.public_key().public_bytes(encoding=serialization.Encoding.PEM,
+                                             format=serialization.PublicFormat.SubjectPublicKeyInfo)
+
+
+def keygen(key_dir: str | os.PathLike | None = None, *, overwrite: bool = False) -> dict[str, str]:
+    """Generate a producer Ed25519 key pair.
+
+    Writes `signing.key` (PKCS8 PEM, mode 0600) and `signing.pub` (SPKI PEM)
+    into key_dir (default ~/.quantbom). Refuses to overwrite an existing key
+    unless asked: a lost private key cannot be recovered, and a replaced one
+    changes the key id every certificate so far names.
+    """
+    serialization, Ed25519PrivateKey = _load_crypto()
+    key_dir = Path(key_dir) if key_dir is not None else DEFAULT_KEY_DIR
+    priv_path, pub_path = key_dir / PRIVATE_KEY_NAME, key_dir / PUBLIC_KEY_NAME
+    if priv_path.exists() and not overwrite:
+        raise FileExistsError(f"{priv_path} exists; pass overwrite=True (quantbom keygen --force) to replace it — "
+                              "certificates already issued name the old key id")
+    key_dir.mkdir(parents=True, exist_ok=True)
+    private = Ed25519PrivateKey.generate()
+    priv_pem = private.private_bytes(encoding=serialization.Encoding.PEM, format=serialization.PrivateFormat.PKCS8,
+                                     encryption_algorithm=serialization.NoEncryption())
+    # owner-only from the first byte: create with 0600, never write then chmod
+    fd = os.open(priv_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR)
+    with os.fdopen(fd, "wb") as fh:
+        fh.write(priv_pem)
+    os.chmod(priv_path, stat.S_IRUSR | stat.S_IWUSR)  # O_TRUNC on an existing file keeps its old mode
+    pub_path.write_bytes(_public_pem(private))
+    return {"private_key": str(priv_path), "public_key": str(pub_path), "key_id": key_id(_public_raw(private))}
+
+
+def resolve_key(key: str | os.PathLike | None = None) -> Path:
+    """The private key to sign with: the argument, else $QUANTBOM_SIGNING_KEY, else ~/.quantbom/signing.key."""
+    candidate = Path(key) if key else (Path(os.environ[KEY_ENV]) if os.environ.get(KEY_ENV) else DEFAULT_KEY_DIR / PRIVATE_KEY_NAME)
+    if not key and not os.environ.get(KEY_ENV) and not candidate.is_file() and (LEGACY_KEY_DIR / PRIVATE_KEY_NAME).is_file():
+        candidate = LEGACY_KEY_DIR / PRIVATE_KEY_NAME
+    if not candidate.is_file():
+        raise FileNotFoundError(f"no signing key at {candidate}: run `quantbom keygen`, or point --key / {KEY_ENV} at your key")
+    return candidate
+
+
+def load_private_key(path: str | os.PathLike):
+    serialization, _ = _load_crypto()
+    return serialization.load_pem_private_key(Path(path).read_bytes(), password=None)
+
+
+def public_key_id(path: str | os.PathLike) -> str:
+    """Key id of a public (SPKI PEM) or private key file."""
+    serialization, _ = _load_crypto()
+    raw = Path(path).read_bytes()
+    try:
+        key = serialization.load_pem_public_key(raw)
+    except ValueError:
+        key = serialization.load_pem_private_key(raw, password=None).public_key()
+    return key_id(key.public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw))
+
+
+def build_statement(sbom: dict[str, Any], base_dir: Path, *, created_at: str,
+                    omit_refs: tuple[str, ...] = ()) -> dict[str, Any]:
+    """The in-toto Statement the producer signs.
+
+    Every referenced artifact present on disk becomes a subject, keyed by the
+    property NAME (not the path) so the signature survives ref rewriting when
+    the bundle is packed. `omit_refs` leaves out artifacts that will not travel
+    (privacy="strict" withholds the circuit IR): the gate verifies each subject
+    against the bytes it received, so a subject it cannot see would read as
+    tampering. Their digests still travel as claimed, hash-bound properties.
+    """
+    props = _properties(sbom)
+    subjects = []
+    for ref_prop in SUBJECT_REF_PROPS:
+        ref = props.get(ref_prop)
+        if not ref or ref_prop in omit_refs:
+            continue
+        path = (base_dir / ref).resolve()
+        if not path.exists():
+            continue
+        subjects.append({"name": ref_prop, "uri": ref, "digest": {"sha256": _sha256(path.read_bytes())}})
+    release_id = release_identity(sbom)
+    return {
+        "_type": "https://in-toto.io/Statement/v1",
+        "subject": subjects,
+        "predicateType": PREDICATE_TYPE,
+        "predicate": {
+            "release_id": release_id,
+            "qbom_profile_version": "0.3.0",
+            "builder": {"id": BUILDER_ID},
+            "signer_role": ROLE,
+            "created_at": created_at,
+        },
+    }
+
+
+def sign(bundle: str | os.PathLike, key: str | os.PathLike | None = None, *,
+         created_at: str | None = None, omit_refs: tuple[str, ...] = ()) -> dict[str, Any]:
+    """Sign a collected bundle as its producer.
+
+    Writes evidence/attestation.json and evidence/signing.pub into the bundle
+    and (re)writes the four producer signing properties on sbom.cdx.json;
+    anything else in the QBOM, including a service countersignature, is left
+    as it was. Signing twice replaces the producer signature.
+    """
+    bundle_dir = Path(bundle)
+    sbom_path = bundle_dir / "sbom.cdx.json"
+    if not sbom_path.is_file():
+        raise FileNotFoundError(f"{bundle_dir} is not an evidence bundle (no sbom.cdx.json); make one with `quantbom collect`")
+    private = load_private_key(resolve_key(key))
+    kid = key_id(_public_raw(private))
+
+    sbom = json.loads(sbom_path.read_text(encoding="utf-8"))
+    statement = build_statement(sbom, bundle_dir, created_at=created_at or _now(), omit_refs=omit_refs)
+    payload = _canonical(statement)
+    envelope = {
+        "payloadType": PAYLOAD_TYPE,
+        "payload": base64.b64encode(payload).decode("ascii"),
+        "signatures": [{"keyid": kid, "sig": base64.b64encode(private.sign(_pae(payload))).decode("ascii")}],
+    }
+    attestation_path = bundle_dir / ATTESTATION_REL
+    _write_json(attestation_path, envelope)
+    (bundle_dir / PUBKEY_REL).write_bytes(_public_pem(private))
+    attestation_sha = "sha256:" + _sha256(attestation_path.read_bytes())
+
+    metadata = sbom.setdefault("metadata", {})
+    kept = [p for p in metadata.get("properties", []) if p.get("name") not in SIGNING_PROPERTY_NAMES]
+    metadata["properties"] = kept + [
+        {"name": "secqdevops:signature-ref", "value": ATTESTATION_REL},
+        {"name": "secqdevops:signing-pubkey-ref", "value": PUBKEY_REL},
+        {"name": "secqdevops:signing-key-id", "value": kid},
+        {"name": "secqdevops:attestation-sha256", "value": attestation_sha},
+    ]
+    _write_json(sbom_path, sbom)
+    return {
+        "release_id": statement["predicate"]["release_id"],
+        "role": ROLE,
+        "key_id": kid,
+        "subjects": len(statement["subject"]),
+        "attestation": str(attestation_path),
+        "attestation_sha256": attestation_sha,
+    }

quantbom/_stats.py

@@ -0,0 +1,125 @@
+"""Statistics behind QBOM-BENCH-02 — one definition for the SDK and the gate.
+
+A measured distribution is a sample. Its total-variation distance (TVD) from a
+declared expectation carries sampling error, so "within tolerance" at 1,024
+shots on a 12-qubit circuit decides nothing. This module makes that explicit:
+
+  * the TVD, computed the one way the collector and the gate both use;
+  * a distribution-free bound on the sampling error of the empirical TVD
+    (Weissman et al. 2003, L1 deviation of the multinomial): with probability
+    at least 1 - alpha,  TVD(empirical, true) <= sqrt(ln((2^k - 2)/alpha) / (2N)),
+    where k is the number of outcome classes. Outcomes the expectation gives
+    no mass are collapsed into one class, which leaves the TVD unchanged and
+    keeps k small: k = |declared support| + 1;
+  * the shots needed for that error to be at most half the tolerance;
+  * a three-way decision: `within` when even the worst-case sampling error
+    keeps the TVD inside the tolerance, `exceeded` when it keeps it outside,
+    and `undecided` otherwise — which the gate reports as N-A, never as PASS
+    or FAIL.
+
+Standard library only. This file is `result_statistics.py` at the repository
+root and, byte for byte, `sdk/quantbom/_stats.py`; the harness contract fails
+when the two differ.
+"""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+CONFIDENCE = 0.95
+
+
+def _frequencies(counts: dict[str, Any], shots: int) -> dict[str, float]:
+    if not shots:
+        return {}
+    return {str(k).replace(" ", ""): float(v) / shots for k, v in (counts or {}).items()}
+
+
+def _declared(expected: dict[str, Any]) -> dict[str, float]:
+    return {str(k).replace(" ", ""): float(v) for k, v in (expected or {}).items()}
+
+
+def total_variation_distance(counts: dict[str, Any], shots: int, expected: dict[str, Any]) -> float:
+    observed, declared = _frequencies(counts, shots), _declared(expected)
+    return 0.5 * sum(abs(observed.get(k, 0.0) - declared.get(k, 0.0)) for k in set(observed) | set(declared))
+
+
+def outcome_classes(expected: dict[str, Any]) -> int:
+    """|declared support| + 1: every undeclared outcome is one class ("other")."""
+    return len(_declared(expected)) + 1
+
+
+def sampling_error(shots: int, k: int, confidence: float = CONFIDENCE) -> float:
+    """Bound on TVD(empirical, true) that holds with probability >= confidence."""
+    if shots <= 0:
+        return float("inf")
+    alpha = 1.0 - confidence
+    classes = max(int(k), 2)
+    return math.sqrt(math.log((2.0 ** classes - 2.0) / alpha) / (2.0 * shots))
+
+
+def required_shots(k: int, tolerance: float, confidence: float = CONFIDENCE) -> int:
+    """Smallest N whose sampling error is at most half the tolerance."""
+    if tolerance <= 0:
+        raise ValueError("tolerance must be positive")
+    alpha = 1.0 - confidence
+    classes = max(int(k), 2)
+    half = tolerance / 2.0
+    return int(math.ceil(math.log((2.0 ** classes - 2.0) / alpha) / (2.0 * half * half)))
+
+
+def decide(tvd: float, error: float, tolerance: float) -> str:
+    if tvd + error <= tolerance:
+        return "within"
+    if tvd - error > tolerance:
+        return "exceeded"
+    return "undecided"
+
+
+NATIVE_VERDICTS = {"within": "agree", "exceeded": "disagree", "undecided": "undecided"}
+
+
+def compare_samples(shared: dict[str, Any], shared_shots: int, native: dict[str, Any], native_shots: int,
+                    tolerance: float, confidence: float = CONFIDENCE) -> dict[str, Any]:
+    """QNT-09: two independent samples of what should be one distribution — the
+    shared-format run and the framework's own simulator — compared by TVD.
+
+    Each empirical distribution is within its own sampling error of the truth,
+    so their TVD is within the sum of the two bounds of the true distance
+    (triangle inequality). The miss probability is split evenly between them,
+    so the bound holds jointly with probability >= confidence. Classes are the
+    outcomes seen in either sample plus one for everything unseen.
+    """
+    a, b = _frequencies(shared, shared_shots), _frequencies(native, native_shots)
+    tvd = 0.5 * sum(abs(a.get(k, 0.0) - b.get(k, 0.0)) for k in set(a) | set(b))
+    k = len(set(a) | set(b)) + 1
+    each = 1.0 - (1.0 - confidence) / 2.0
+    error = sampling_error(shared_shots, k, each) + sampling_error(native_shots, k, each)
+    return {
+        "tvd": round(tvd, 6),
+        "shared_shots": int(shared_shots),
+        "native_shots": int(native_shots),
+        "classes": k,
+        "confidence": confidence,
+        "sampling_error": round(error, 6) if math.isfinite(error) else None,
+        "tolerance": float(tolerance),
+        "verdict": NATIVE_VERDICTS[decide(tvd, error, tolerance)],
+    }
+
+
+def assess(counts: dict[str, Any], shots: int, expected: dict[str, Any], tolerance: float,
+           confidence: float = CONFIDENCE) -> dict[str, Any]:
+    """Everything QBOM-BENCH-02 records, from the measured counts and the declaration."""
+    k = outcome_classes(expected)
+    tvd = total_variation_distance(counts, shots, expected)
+    error = sampling_error(shots, k, confidence)
+    return {
+        "tvd": round(tvd, 6),
+        "shots": int(shots),
+        "classes": k,
+        "confidence": confidence,
+        "sampling_error": round(error, 6) if math.isfinite(error) else None,
+        "required_shots": required_shots(k, tolerance, confidence),
+        "tolerance": float(tolerance),
+        "verdict": decide(tvd, error, tolerance),
+    }