quantbom 0.6.0__py3-none-any.whl

quantbom/_verify.py

@@ -0,0 +1,530 @@
+"""Offline verification from a pip install — hybrid signing model, step 2 (MVP_PLAN.md B2).
+
+    quantbom keys --pin                    # fetch the service's signing keys once, pin them
+    quantbom verify .quantbom/my-app@1.0    # a mirror directory, a collected bundle, or a zip of either
+
+An auditor who should not have to trust QuantBOM, or install its service code,
+re-derives from the bytes in front of them everything that can be re-derived
+without the gate:
+
+  artifact_hashes        every hash-bound artifact re-hashed against the QBOM, and
+                         every claim bound to a hash-verified report compared with it
+  evidence_signatures    the producer's attestation and the service's receipt:
+                         Ed25519 over the DSSE PAE, key ids, roles, subjects vs bytes
+  csnap_bindings         the CSNAP's reproducibility hash recomputed from its own
+                         payload; its input digest is this QBOM; its counts and
+                         verdict follow from its control results
+  certificate_bindings   the certificate's reproducibility hash recomputed; it names
+                         this CSNAP and this QBOM; its evidence_signing block names the
+                         keys the QBOM names; requirement statuses follow from the
+                         control statuses they list, the overall status from them
+  certificate_signature  Ed25519 over the certificate bytes, by a key that is ANCHORED:
+                         pinned from /v1/keys, or supplied — never only the key the
+                         bundle itself carries
+
+What it does not do, and says so: re-run the gate's controls. That needs the gate
+(python verify_bundle.py in the repository), and the verdict here is about
+integrity and authorship, not policy. Verdicts: VERIFIED, FAILED, or UNANCHORED
+when every check passed but no trust anchor was available for the service key.
+
+The lists below mirror the gate's (mod08_cyclonedx_prototype.py);
+tests/harness/test_sdk_verify.py pins each pair equal.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+import urllib.request
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ._sign import release_identity
+
+from ._sign import ATTESTATION_REL, PAYLOAD_TYPE, PUBKEY_REL, SigningUnavailable, _pae, key_id
+
+# ---- the gate's binding tables, mirrored ----------------------------------
+HASH_VERIFIED_ARTIFACT_PAIRS = [
+    ("secqdevops:circuit-artifact-ref", "secqdevops:circuit-sha256"),
+    ("secqdevops:transpiled-circuit-ref", "secqdevops:transpiled-circuit-sha256"),
+    ("secqdevops:qasm-program-ref", "secqdevops:qasm-program-sha256"),
+    ("secqdevops:qir-program-ref", "secqdevops:qir-program-sha256"),
+    ("secqdevops:qir-consistency-ref", "secqdevops:qir-consistency-sha256"),
+    ("secqdevops:benchmark-ref", "secqdevops:benchmark-sha256"),
+    ("secqdevops:equivalence-ref", "secqdevops:equivalence-sha256"),
+    ("secqdevops:conversion-fidelity-ref", "secqdevops:conversion-fidelity-sha256"),
+    ("secqdevops:native-program-ref", "secqdevops:native-program-sha256"),
+    ("secqdevops:harness-log-ref", "secqdevops:harness-log-sha256"),
+    ("secqdevops:error-handling-ref", "secqdevops:error-handling-sha256"),
+    ("secqdevops:expected-distribution-ref", "secqdevops:expected-distribution-sha256"),
+    ("secqdevops:calibration-ref", "secqdevops:calibration-sha256"),
+    ("secqdevops:ct-proof-ref", "secqdevops:ct-proof-sha256"),
+    ("secqdevops:cbom-ref", "secqdevops:cbom-sha256"),
+    ("secqdevops:crypto-agility-ref", "secqdevops:crypto-agility-sha256"),
+    ("secqdevops:vex-ref", "secqdevops:vex-sha256"),
+    ("secqdevops:cvd-policy-ref", "secqdevops:cvd-policy-sha256"),
+    ("secqdevops:test-report-ref", "secqdevops:test-report-sha256"),
+    ("secqdevops:backend-target-ref", "secqdevops:backend-target-sha256"),
+    ("secqdevops:runtime-job-ref", "secqdevops:runtime-job-sha256"),
+    ("secqdevops:result-summary-ref", "secqdevops:result-summary-sha256"),
+    ("secqdevops:native-result-ref", "secqdevops:native-result-sha256"),
+]
+DIGEST_OPTIONAL_REFS = {
+    "secqdevops:backend-target-ref",
+    "secqdevops:runtime-job-ref",
+    "secqdevops:result-summary-ref",
+}
+STRICT_WITHHOLDABLE_REFS = {
+    "secqdevops:circuit-artifact-ref",
+    "secqdevops:transpiled-circuit-ref",
+    "secqdevops:qasm-program-ref",
+}
+VERDICT_BOUND_REPORTS = {
+    "secqdevops:equivalence-ref": "secqdevops:equivalence-verdict",
+    "secqdevops:conversion-fidelity-ref": "secqdevops:conversion-fidelity-verdict",
+    "secqdevops:qir-consistency-ref": "secqdevops:qir-consistency-verdict",
+    "secqdevops:native-result-ref": "secqdevops:native-result-verdict",
+}
+CLAIM_BOUND_REPORTS = {
+    "secqdevops:runtime-job-ref": [("secqdevops:runtime-job-status", "job_status")],
+    "secqdevops:backend-target-ref": [("secqdevops:execution-target", "execution_target")],
+    "secqdevops:error-handling-ref": [("secqdevops:error-mitigation", "mitigation_status")],
+    "secqdevops:calibration-ref": [("secqdevops:calibration-age-hours", "calibration_age_hours"),
+                                  ("secqdevops:calibration-captured-at", "captured_at")],
+    "secqdevops:equivalence-ref": [("secqdevops:equivalence-kind", "equivalence_kind")],
+    "secqdevops:conversion-fidelity-ref": [("secqdevops:conversion-fidelity-method", "method"),
+                                          ("secqdevops:native-program-sha256", "native_export_sha256")],
+}
+# the two signing roles, as the gate's sign_evidence.ROLES names them
+ROLES = {
+    "producer": {"ref": "secqdevops:signature-ref", "pub": "secqdevops:signing-pubkey-ref", "kid": "secqdevops:signing-key-id"},
+    "service": {"ref": "secqdevops:service-attestation-ref", "pub": "secqdevops:service-signing-pubkey-ref",
+                "kid": "secqdevops:service-signing-key-id"},
+}
+# the fields whose canonical JSON the reproducibility hashes are taken over
+# (the gate's CSNAP_PAYLOAD_KEYS; certify.py's CERTIFICATE_PAYLOAD_KEYS)
+CSNAP_PAYLOAD_KEYS = ("release_id", "catalogue_version", "overall_status", "summary", "control_results",
+                      "evidence_completeness", "findings", "input_digests")
+CERTIFICATE_PAYLOAD_KEYS = ("scheme", "scheme_long", "assessment_type", "mapping_version", "standards_basis", "privacy_mode",
+                            "evidence_signing", "evidence_validity", "subject", "overall_status", "coverage", "requirements", "gaps")
+
+PINNED_KEYS = Path.home() / ".quantbom" / "service-keys.json"
+LEGACY_PINNED_KEYS = Path.home() / ".zentroq" / "service-keys.json"  # pinned before the rename (0.6.0)
+MIRROR_SIGNING_PUB = "signing.pub"  # the service's certificate key, as the mirror receives it
+
+
+# ---- small helpers, kept identical in effect to the gate's ------------------
+def _sha256_bytes(raw: bytes) -> str:
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def _sha256_json(data: Any) -> str:
+    return _sha256_bytes(json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("utf-8"))
+
+
+def _is_sha256(value: str | None) -> bool:
+    if not value or not value.startswith("sha256:"):
+        return False
+    digest = value.split(":", 1)[1]
+    return len(digest) == 64 and all(c in "0123456789abcdef" for c in digest.lower())
+
+
+def _props(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 _load(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _check(name: str, passed: bool, detail: Any) -> dict[str, Any]:
+    return {"check": name, "status": "PASS" if passed else "FAIL", "detail": detail}
+
+
+def _crypto():
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import serialization
+    except ImportError as exc:
+        raise SigningUnavailable('verifying signatures needs the cryptography package: pip install "quantbom[signing]"') from exc
+    return serialization, InvalidSignature
+
+
+def _raw_public(public_key) -> bytes:
+    serialization, _ = _crypto()
+    return public_key.public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw)
+
+
+# ---- 1. artifact hashes and bound claims -----------------------------------
+def check_artifacts(sbom: dict[str, Any], base_dir: Path) -> dict[str, Any]:
+    props = _props(sbom)
+    strict = props.get("secqdevops:privacy-mode") == "strict"
+    findings: list[str] = []
+    checked = attested = 0
+    for ref_prop, sha_prop in HASH_VERIFIED_ARTIFACT_PAIRS:
+        ref, claimed = props.get(ref_prop), props.get(sha_prop)
+        if not ref and not claimed:
+            continue
+        if ref and not claimed and ref_prop in DIGEST_OPTIONAL_REFS:
+            continue  # a declaration without a digest: unverified, not invalid (the gate's rule)
+        if not ref or not claimed:
+            findings.append(f"{ref_prop}/{sha_prop} must be provided together"); continue
+        if not _is_sha256(claimed):
+            findings.append(f"{sha_prop} is not a valid sha256:<digest> value"); continue
+        path = Path(ref) if Path(ref).is_absolute() else (base_dir / ref).resolve()
+        if not path.exists():
+            if strict and ref_prop in STRICT_WITHHOLDABLE_REFS:
+                attested += 1  # withheld on purpose: the digest is the producer's claim, auditable on-site
+                continue
+            findings.append(f"referenced artifact for {ref_prop} not found: {ref}"); continue
+        raw = path.read_bytes()
+        actual = _sha256_bytes(raw)
+        if actual != claimed:
+            findings.append(f"hash mismatch for {ref_prop} ({ref}): QBOM claims {claimed}, bytes hash to {actual}"); continue
+        checked += 1
+        # a verdict or claim declared beside a hash-verified report must be the report's own
+        bound = [(VERDICT_BOUND_REPORTS[ref_prop], "verdict")] if ref_prop in VERDICT_BOUND_REPORTS else []
+        bound += CLAIM_BOUND_REPORTS.get(ref_prop, [])
+        if not bound:
+            continue
+        try:
+            doc = json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            findings.append(f"{ref_prop} ({ref}) is not a readable JSON report"); continue
+        for claim_prop, field in bound:
+            if claim_prop not in props and field != "verdict":
+                continue  # claims are checked when declared; a verdict is always expected
+            declared = str(props.get(claim_prop, "")).lower()
+            in_file = str((doc.get(field, "") if isinstance(doc, dict) else "")).lower()
+            if declared != in_file:
+                findings.append(f"{claim_prop} declares {declared or '(none)'!r} but the hash-verified {ref} records "
+                                f"{in_file or '(none)'!r} — evidence is internally inconsistent")
+    detail = findings or f"{checked} artifact(s) re-hashed and match the QBOM" + (f"; {attested} withheld (privacy strict), digests client-attested" if attested else "")
+    return _check("artifact_hashes", not findings, detail)
+
+
+# ---- 2. evidence signatures (producer attestation, service receipt) ----------
+def _verify_role(role: str, props: dict[str, str], base_dir: Path) -> list[str]:
+    serialization, InvalidSignature = _crypto()
+    spec = ROLES[role]
+    att_path, pub_path = (base_dir / props[spec["ref"]]).resolve(), (base_dir / props[spec["pub"]]).resolve()
+    if not att_path.exists() or not pub_path.exists():
+        return [f"attestation or public key not found ({props[spec['ref']]}, {props[spec['pub']]})"]
+    envelope = _load(att_path)
+    public_key = serialization.load_pem_public_key(pub_path.read_bytes())
+    payload = base64.b64decode(envelope["payload"])
+    try:
+        public_key.verify(base64.b64decode(envelope["signatures"][0]["sig"]), _pae(payload))
+    except InvalidSignature:
+        return ["Ed25519 signature does not verify against the declared public key"]
+    findings: list[str] = []
+    if envelope.get("payloadType") != PAYLOAD_TYPE:
+        findings.append(f"unexpected payloadType {envelope.get('payloadType')!r}")
+    actual_kid = key_id(_raw_public(public_key))
+    env_kid = str(envelope["signatures"][0].get("keyid") or "")
+    if env_kid and env_kid != actual_kid:
+        findings.append(f"attestation keyid {env_kid[:19]}… is not the bundled public key's id {actual_kid[:19]}…")
+    declared = props.get(spec["kid"])
+    if declared and declared != actual_kid:
+        findings.append(f"{spec['kid']} {declared[:19]}… is not the bundled public key's id {actual_kid[:19]}…")
+    statement = json.loads(payload)
+    stated_role = statement.get("predicate", {}).get("signer_role")
+    if stated_role and stated_role != role:
+        findings.append(f"attestation declares signer_role {stated_role!r} but is referenced as the {role} signature")
+    for subject in statement.get("subject", []):
+        ref_prop, claimed = subject["name"], subject["digest"]["sha256"]
+        value = props.get(ref_prop)
+        if not value:
+            findings.append(f"signed subject property not present in QBOM: {ref_prop}"); continue
+        artifact = (base_dir / value).resolve()
+        if not artifact.exists():
+            findings.append(f"signed subject not found on disk: {ref_prop} -> {value}"); continue
+        actual = hashlib.sha256(artifact.read_bytes()).hexdigest()
+        if actual != claimed:
+            findings.append(f"signed subject {ref_prop} tampered: attestation {claimed[:12]}… != bytes {actual[:12]}…")
+    return findings
+
+
+def signers(sbom: dict[str, Any], base_dir: Path) -> list[dict[str, Any]]:
+    """Every signature the QBOM declares, verified: [{role, key_id, ok, findings}] (the gate's `signers`)."""
+    props = _props(sbom)
+    out = []
+    for role, spec in ROLES.items():
+        if not (props.get(spec["ref"]) and props.get(spec["pub"])):
+            continue  # the collector's unsigned placeholder (signature-ref alone) is not a signature
+        try:
+            findings = _verify_role(role, props, base_dir)
+        except SigningUnavailable:
+            raise
+        except Exception as exc:  # an unreadable envelope or key is a finding, not a crash
+            findings = [f"could not verify: {type(exc).__name__}: {exc}"]
+        out.append({"role": role, "key_id": props.get(spec["kid"]), "ok": not findings, "findings": findings})
+    return out
+
+
+def check_evidence_signatures(sbom: dict[str, Any], base_dir: Path) -> dict[str, Any]:
+    """The gate's rule (sign_evidence.verify): the producer's signature must be there and hold;
+    a service receipt must hold if present, and never stands in for the producer."""
+    present = signers(sbom, base_dir)
+    findings = [f"{s['role']}: {f}" for s in present for f in s["findings"]]
+    if not any(s["role"] == "producer" for s in present):
+        findings.insert(0, "no producer signature" + (" (service receipt only: a receipt is not authorship)" if present else " and no service countersignature")
+                        + " — the releasing organisation signs with quantbom keygen / quantbom sign")
+    roles = " + ".join(s["role"] for s in present)
+    return _check("evidence_signatures", not findings, findings or f"{roles} signature(s) valid; key ids match; subjects match the bytes")
+
+
+# ---- 3. the CSNAP is bound to this QBOM and to itself -------------------------
+def check_csnap(sbom: dict[str, Any], csnap: dict[str, Any]) -> dict[str, Any]:
+    findings: list[str] = []
+    claimed_sbom = csnap.get("input_digests", {}).get("sbom_sha256")
+    if claimed_sbom != _sha256_json(sbom):
+        findings.append(f"the CSNAP was computed over a different QBOM (input sbom_sha256 {str(claimed_sbom)[:19]}… != this file {_sha256_json(sbom)[:19]}…)")
+    missing = [k for k in CSNAP_PAYLOAD_KEYS if k not in csnap]
+    if missing:
+        findings.append(f"CSNAP lacks payload fields {missing}")
+    elif _sha256_json({k: csnap[k] for k in CSNAP_PAYLOAD_KEYS}) != csnap.get("reproducibility_hash"):
+        findings.append("CSNAP reproducibility_hash is not the hash of its own payload (contents edited after the gate ran)")
+    results = csnap.get("control_results", [])
+    counts = {s: sum(1 for r in results if r.get("status") == s) for s in ("PASS", "FAIL", "N-A")}
+    summary = csnap.get("summary", {})
+    expect = {"total_controls": len(results), "passed": counts["PASS"], "failed": counts["FAIL"], "not_applicable": counts["N-A"]}
+    if any(summary.get(k) != v for k, v in expect.items()):
+        findings.append(f"CSNAP summary {summary} does not count its control results {expect}")
+    verdict = "COMPLIANT" if counts["FAIL"] == 0 else "NON_COMPLIANT"
+    if csnap.get("overall_status") != verdict:
+        findings.append(f"CSNAP overall_status {csnap.get('overall_status')!r} but its control results give {verdict!r}")
+    return _check("csnap_bindings", not findings, findings or f"hash recomputed; computed over this QBOM; {counts['PASS']} PASS / {counts['FAIL']} FAIL / {counts['N-A']} N-A give {verdict}")
+
+
+# ---- 4. the certificate is bound to the CSNAP, the QBOM and its own arithmetic ----
+def check_certificate(sbom: dict[str, Any], csnap: dict[str, Any] | None, cert: dict[str, Any]) -> dict[str, Any]:
+    findings: list[str] = []
+    missing = [k for k in CERTIFICATE_PAYLOAD_KEYS if k not in cert]
+    if missing:
+        findings.append(f"certificate lacks payload fields {missing}")
+    elif _sha256_json({k: cert[k] for k in CERTIFICATE_PAYLOAD_KEYS}) != cert.get("reproducibility_hash"):
+        findings.append("certificate reproducibility_hash is not the hash of its own payload (contents edited after issue)")
+    subject = cert.get("subject", {})
+    if subject.get("sbom_sha256") != _sha256_json(sbom):
+        findings.append("the certificate's subject is a different QBOM (subject.sbom_sha256 differs from this file)")
+    if subject.get("sbom_serial") and subject.get("sbom_serial") != sbom.get("serialNumber"):
+        findings.append("the certificate's subject.sbom_serial is not this QBOM's serialNumber")
+    if csnap is not None:
+        if subject.get("csnap_reproducibility_hash") != csnap.get("reproducibility_hash") or subject.get("csnap_id") != csnap.get("csnap_id"):
+            findings.append("the certificate names a different CSNAP than the one beside it")
+        by_id = {r["control_id"]: r.get("status") for r in csnap.get("control_results", [])}
+        for req in cert.get("requirements", []):
+            for c in req.get("controls", []):
+                if by_id.get(c["control_id"]) != c.get("status"):
+                    findings.append(f"requirement {req['id']} lists {c['control_id']} as {c.get('status')}, the CSNAP says {by_id.get(c['control_id'])}")
+    # who signed: the certificate's statement must be the QBOM's
+    props = _props(sbom)
+    es = cert.get("evidence_signing", {})
+    producer = props.get("secqdevops:signing-key-id") if props.get("secqdevops:signing-pubkey-ref") else None
+    service = props.get("secqdevops:service-signing-key-id") if props.get("secqdevops:service-signing-pubkey-ref") else None
+    if (es.get("producer_key_id"), es.get("service_key_id")) != (producer, service):
+        findings.append(f"certificate evidence_signing names keys {es.get('producer_key_id')!r}/{es.get('service_key_id')!r}; the QBOM names {producer!r}/{service!r}")
+    if cert.get("privacy_mode", "standard") != props.get("secqdevops:privacy-mode", "standard"):
+        findings.append("certificate privacy_mode differs from the QBOM's")
+    # requirement statuses follow from the control statuses they list; the overall status from them
+    n_sat = n_unsat = n_uncov = 0
+    for req in cert.get("requirements", []):
+        present = req.get("controls", [])
+        effective = [c for c in present if c.get("status") in ("PASS", "FAIL")]
+        if not present or not effective:
+            expect = "NOT_COVERED"
+        elif any(c.get("status") == "FAIL" for c in present):
+            expect = "NOT_SATISFIED"
+        else:
+            expect = "SATISFIED"
+        if req.get("status") != expect:
+            findings.append(f"requirement {req.get('id')} is {req.get('status')} but its controls give {expect}")
+        n_sat += expect == "SATISFIED"; n_unsat += expect == "NOT_SATISFIED"; n_uncov += expect == "NOT_COVERED"
+    overall = "NON_COMPLIANT" if n_unsat else ("CRA-ALIGNED" if n_uncov == 0 else "PARTIALLY_ASSESSED")
+    if cert.get("requirements") and cert.get("overall_status") != overall:
+        findings.append(f"certificate overall_status {cert.get('overall_status')!r} but its requirements give {overall!r}")
+    cov = cert.get("coverage", {})
+    if cert.get("requirements") and (cov.get("satisfied"), cov.get("not_satisfied"), cov.get("not_covered")) != (n_sat, n_unsat, n_uncov):
+        findings.append(f"certificate coverage {cov} does not count its requirements ({n_sat}/{n_unsat}/{n_uncov})")
+    return _check("certificate_bindings", not findings, findings or
+                  f"hash recomputed; names this QBOM{' and this CSNAP' if csnap is not None else ''}; signers as the QBOM declares; "
+                  f"{n_sat} satisfied / {n_unsat} not satisfied / {n_uncov} not covered give {overall}")
+
+
+# ---- 5. the certificate signature, by an anchored key -------------------------
+def load_anchor(keys_file: str | os.PathLike | None = None, service_key: str | os.PathLike | None = None) -> dict[str, Any] | None:
+    """Trusted service keys {key_id: {pem, status}} and where they came from; None when nothing is anchored."""
+    serialization, _ = _crypto()
+    if service_key:
+        pem = Path(service_key).read_bytes()
+        kid = key_id(_raw_public(serialization.load_pem_public_key(pem)))
+        return {"source": f"--service-key {service_key}", "keys": {kid: {"pem": pem.decode("ascii"), "status": "supplied"}}}
+    path = Path(keys_file) if keys_file else next((k for k in (PINNED_KEYS, LEGACY_PINNED_KEYS) if k.is_file()), None)
+    if path is None:
+        return None
+    doc = _load(path)
+    keys = {}
+    for k in doc.get("keys", []):
+        pem = k["public_key_pem"]
+        kid = key_id(_raw_public(serialization.load_pem_public_key(pem.encode("ascii"))))
+        if k.get("key_id") and k["key_id"] != kid:
+            raise ValueError(f"{path}: key {k['key_id'][:19]}… is not the id of the key beside it ({kid[:19]}…) — the file is corrupt")
+        keys[kid] = {"pem": pem, "status": k.get("status", "current")}
+    label = "pinned " + str(path) + (f" (fetched {doc['fetched_at']} from {doc['api_url']})" if doc.get("fetched_at") else "")
+    return {"source": label, "keys": keys}
+
+
+def check_certificate_signature(cert_path: Path, att_path: Path, bundled_pub: Path | None, anchor: dict[str, Any] | None) -> dict[str, Any]:
+    serialization, InvalidSignature = _crypto()
+    envelope = _load(att_path)
+    env_kid = str(envelope["signatures"][0].get("keyid") or "")
+    payload = base64.b64decode(envelope["payload"])
+    sig = base64.b64decode(envelope["signatures"][0]["sig"])
+    anchored = anchor is not None and env_kid in anchor["keys"]
+    if anchor is not None and not anchored:
+        return _check("certificate_signature", False,
+                      f"signed by key {env_kid[:19]}…, which is not among the trusted service keys ({anchor['source']}: {[k[:19] + '…' for k in anchor['keys']] or 'none'})")
+    if anchored:
+        pem = anchor["keys"][env_kid]["pem"].encode("ascii")
+        if anchor["keys"][env_kid]["status"] == "revoked":
+            return _check("certificate_signature", False, f"signed by key {env_kid[:19]}…, which the service lists as REVOKED")
+    elif bundled_pub is not None and bundled_pub.is_file():
+        pem = bundled_pub.read_bytes()
+    else:
+        return _check("certificate_signature", False, "no public key to verify with: pin the service keys (quantbom keys --pin) or pass --keys / --service-key")
+    public_key = serialization.load_pem_public_key(pem)
+    actual_kid = key_id(_raw_public(public_key))
+    if env_kid and env_kid != actual_kid:
+        return _check("certificate_signature", False, f"attestation keyid {env_kid[:19]}… is not the id of the key it is verified with ({actual_kid[:19]}…)")
+    try:
+        public_key.verify(sig, _pae(payload))
+    except InvalidSignature:
+        return _check("certificate_signature", False, "Ed25519 signature does not verify against the service key")
+    statement = json.loads(payload)
+    claimed = statement["subject"][0]["digest"]["sha256"]
+    actual = hashlib.sha256(cert_path.read_bytes()).hexdigest()
+    if actual != claimed:
+        return _check("certificate_signature", False, f"certificate bytes changed since signing: {claimed[:12]}… != {actual[:12]}…")
+    status = anchor["keys"][env_kid]["status"] if anchored else None
+    detail = (f"valid; key {env_kid[:19]}… is anchored ({status}; {anchor['source']})" if anchored
+              else f"valid against the key the bundle carries ({env_kid[:19]}…) — NOT anchored: run `quantbom keys --pin` or pass --keys")
+    out = _check("certificate_signature", True, detail)
+    out["anchored"] = anchored
+    return out
+
+
+# ---- locating the pieces -----------------------------------------------------
+class Located:
+    def __init__(self, path: Path, certificate: Path | None = None):
+        self.tmp: str | None = None
+        root = Path(path)
+        if root.is_file() and zipfile.is_zipfile(root):
+            self.tmp = tempfile.mkdtemp(prefix="quantbom-verify-")
+            with zipfile.ZipFile(root) as zf:
+                zf.extractall(self.tmp)
+            inner = [p for p in Path(self.tmp).iterdir() if p.is_dir()]
+            root = inner[0] if len(inner) == 1 and not (Path(self.tmp) / "sbom.cdx.json").exists() else Path(self.tmp)
+        if not root.is_dir():
+            raise FileNotFoundError(f"{path} is not a directory or a zip")
+        if (root / "sbom.cdx.json").is_file():
+            self.sbom, self.base = root / "sbom.cdx.json", root
+        elif (root / "evidence" / "sbom.cdx.json").is_file():  # an AEXP: refs resolve from the bundle root
+            self.sbom, self.base = root / "evidence" / "sbom.cdx.json", root
+        else:
+            raise FileNotFoundError(f"{path}: no sbom.cdx.json (a mirror directory under .quantbom/, a `quantbom collect` bundle, or an AEXP zip)")
+        self.root = root
+        self.csnap = root / "csnap.json" if (root / "csnap.json").is_file() else None
+        cert = Path(certificate) if certificate else root / "certificate.json"
+        self.cert = cert if cert.is_file() else None
+        att = cert.with_name(cert.name + ".att.json")
+        self.cert_att = att if att.is_file() else None
+        self.cert_pub = cert.with_name(MIRROR_SIGNING_PUB) if cert.with_name(MIRROR_SIGNING_PUB).is_file() else (
+            root / "evidence" / "signing.pub" if self.base != root and (root / "evidence" / "signing.pub").is_file() else None)
+
+    def close(self) -> None:
+        if self.tmp:
+            shutil.rmtree(self.tmp, ignore_errors=True)
+
+
+# ---- the verdict ---------------------------------------------------------------
+def verify(path: str | os.PathLike, *, certificate: str | os.PathLike | None = None,
+           keys_file: str | os.PathLike | None = None, service_key: str | os.PathLike | None = None) -> dict[str, Any]:
+    """Verify a mirror directory, a collected bundle, or a zip of either. See the module docstring."""
+    loc = Located(path, certificate)
+    try:
+        sbom = _load(loc.sbom)
+        checks = [check_artifacts(sbom, loc.base), check_evidence_signatures(sbom, loc.base)]
+        csnap = _load(loc.csnap) if loc.csnap else None
+        cert = _load(loc.cert) if loc.cert else None
+        if csnap is not None:
+            checks.append(check_csnap(sbom, csnap))
+        if cert is not None:
+            checks.append(check_certificate(sbom, csnap, cert))
+            if loc.cert_att is not None:
+                checks.append(check_certificate_signature(loc.cert, loc.cert_att, loc.cert_pub, load_anchor(keys_file, service_key)))
+            else:
+                checks.append(_check("certificate_signature", False, "certificate.json.att.json not found beside the certificate: the certificate is unsigned"))
+        failed = [c["check"] for c in checks if c["status"] != "PASS"]
+        anchored = any(c.get("anchored") for c in checks if c["check"] == "certificate_signature")
+        verdict = "FAILED" if failed else ("VERIFIED" if cert is None or anchored else "UNANCHORED")
+        return {
+            "verdict": verdict,
+            **({"service_checks": csnap["service_checks"]} if csnap and csnap.get("service_checks") else {}),
+            "release_id": release_identity(sbom),
+            "certificate_id": (cert or {}).get("certificate_id"),
+            "source": str(path),
+            "independent": True,
+            "anchored": anchored,
+            "checks": checks,
+            "not_checked": ["control verdicts: the gate's controls were not re-evaluated here (python verify_bundle.py in the "
+                            "QuantBOM repository re-runs the gate); this verdict covers integrity and authorship, not policy"],
+            "note": ("digests, signatures and bindings re-derived from bytes; claimed status fields were not trusted"
+                     + ("" if verdict != "UNANCHORED" else "; every check passed but the service key is only the one the bundle carries — "
+                        "pin the service's keys (quantbom keys --pin) and verify again")),
+        }
+    finally:
+        loc.close()
+
+
+# ---- pinning the service's keys -------------------------------------------------
+def pin_keys(api_url: str, out: str | os.PathLike | None = None) -> dict[str, Any]:
+    """Fetch /v1/keys once and store it, with provenance, as the local trust anchor."""
+    serialization, _ = _crypto()
+    url = api_url.rstrip("/") + "/v1/keys"
+    with urllib.request.urlopen(urllib.request.Request(url, headers={"Accept": "application/json"}), timeout=30) as resp:
+        doc = json.loads(resp.read().decode("utf-8"))
+    for k in doc.get("keys", []):  # refuse a document whose key ids do not match its keys
+        kid = key_id(_raw_public(serialization.load_pem_public_key(k["public_key_pem"].encode("ascii"))))
+        if k.get("key_id") != kid:
+            raise ValueError(f"{url}: key {k.get('key_id')} is not the id of the key beside it ({kid}); not pinned")
+    doc["api_url"] = api_url.rstrip("/")
+    doc["fetched_at"] = datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+    path = Path(out) if out else PINNED_KEYS
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(doc, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+    return {"pinned": str(path), "api_url": doc["api_url"], "fetched_at": doc["fetched_at"],
+            "keys": [{"key_id": k["key_id"], "status": k.get("status"), "pem_sha256": k.get("pem_sha256")} for k in doc.get("keys", [])],
+            "notes": doc.get("notes", [])}
+
+
+def render(report: dict[str, Any]) -> str:
+    lines = [f"{report['verdict']}  {report.get('release_id') or '?'}" + (f"  {report['certificate_id']}" if report.get("certificate_id") else "")]
+    for c in report["checks"]:
+        mark = "■" if c["status"] == "PASS" else "✗"
+        detail = c["detail"] if isinstance(c["detail"], str) else "; ".join(map(str, c["detail"]))
+        lines.append(f"  {mark} {c['check']:<22} {detail}")
+    for cid, sc in (report.get("service_checks") or {}).items():
+        what = (f"{sc.get('verdict')} ({sc.get('kind')}) with {sc.get('tool')}, {'agrees' if sc.get('agrees') else 'disagrees'} with the producer"
+                if sc.get("attempted") else f"not attempted: {sc.get('note')}")
+        lines.append(f"  · {cid:<22} re-derived by the issuing service: {what}")
+    for n in report.get("not_checked", []):
+        lines.append(f"  □ {n}")
+    lines.append(f"  {report['note']}")
+    return "\n".join(lines)

quantbom/actions/__init__.py

@@ -0,0 +1,27 @@
+"""Harness action registry (HARNESS_PLAN.md §2.2).
+
+Execution order follows data dependencies: capture -> execute -> bind_backend
+(uses the run's backend) -> disclose_error_handling -> check_results ->
+compare_native (needs the run's counts) -> check_qir -> benchmark (records the
+declared expectation) -> prove_equivalence -> verify_conversion ->
+record_provenance -> inventory. Property ORDER in the QBOM is independent of this: see layout.py.
+"""
+from __future__ import annotations
+
+from . import (bind_backend, benchmark, capture, check_qir, check_results, compare_native, disclose_error_handling,
+               execute, inventory, prove_equivalence, record_provenance, verify_conversion)
+from .base import ActionResult, Context
+from .layout import PROPERTY_ORDER, assemble
+
+# Recorded in every QBOM and harness log; must equal harness_manifest.json.
+HARNESS_VERSION = "0.16.0"
+
+REGISTRY = (capture, execute, bind_backend, disclose_error_handling, check_results, compare_native, check_qir, benchmark,
+            prove_equivalence, verify_conversion, record_provenance, inventory)
+
+
+def run_all(ctx: Context) -> list[ActionResult]:
+    return [action.run(ctx) for action in REGISTRY]
+
+
+__all__ = ["HARNESS_VERSION", "REGISTRY", "PROPERTY_ORDER", "ActionResult", "Context", "assemble", "run_all"]

quantbom/actions/base.py

@@ -0,0 +1,68 @@
+"""Harness actions (HARNESS_PLAN.md §2.2).
+
+Each action is one regulation-mapped verb: it reads what earlier actions put
+on the shared context, writes its own artifacts, and returns the QBOM
+properties it emits together with an outcome — never a silent skip.
+
+Outcomes: `produced`, `not_requested` (opt-in not asked for),
+`not_applicable(reason)` (cannot apply to this input) and
+`unsupported(reason)` (the toolchain or framework cannot do it).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+PRODUCED = "produced"
+NOT_REQUESTED = "not_requested"
+NOT_APPLICABLE = "not_applicable"
+UNSUPPORTED = "unsupported"
+
+
+@dataclass
+class Context:
+    """Inputs plus the blackboard actions read from and write to."""
+
+    release_id: str
+    out_dir: Path
+    qiskit_circuit: Any
+    qrisp_circuit: Any
+    frontend_label: str
+    source_format: str
+    backend_choice: str
+    equivalence_check: bool
+    expected_distribution: dict[str, float] | None
+    expected_tolerance: float
+    expected_declaration: dict[str, Any] | None
+    conversion_fidelity: dict[str, Any] | None
+    qiskit_version: str
+    qrisp_version: str
+    #: (text, format) of the native program as the framework exports it — the
+    #: bytes QNT-06 compared; written hash-bound so the native program itself is
+    #: fingerprinted, not only the report about it (FRAMEWORK_REGULATION_MAP §5)
+    native_export: tuple[str, str] | None = None
+    #: the native program sampled on the framework's own simulator (QNT-09):
+    #: an adapter's native_run() result plus "framework"/"shots", or {"reason": …}
+    #: when it could not run; None for Qiskit and file inputs, which are the
+    #: shared format itself
+    native_result: dict[str, Any] | None = None
+    #: preconditions found by _circuit.inspect_circuit (unbound parameters, dynamic features)
+    circuit_info: dict[str, Any] = field(default_factory=dict)
+    state: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def quantum_dir(self) -> Path:
+        return self.out_dir / "quantum"
+
+    @property
+    def evidence_dir(self) -> Path:
+        return self.out_dir / "evidence"
+
+
+@dataclass
+class ActionResult:
+    action: str
+    outcome: str
+    properties: list[dict[str, str]] = field(default_factory=list)
+    reason: str | None = None