fuin 1.0.0__py3-none-any.whl

fuin/__init__.py

@@ -0,0 +1,5 @@
+from pathlib import Path
+
+# The verifier's policies: shipped inside the package when installed (uv tool install, pip), else policy/ in the checkout.
+POLICY = next((p for p in (Path(__file__).parent / "policy", Path(__file__).resolve().parents[2] / "policy") if p.is_dir()),
+              Path(__file__).resolve().parents[2] / "policy")

fuin/asker.py

@@ -0,0 +1,161 @@
+"""Enclave-asked rounds (audit mode tee-asked-v1): the owner side.
+
+The asker (ask/, a wasm32-wasip2 build pinned in policy/tee-v2.json `askers`) runs as an OutLayer project whose owner
+account holds no keys, so its code and its storage can't be changed or wiped. For each sealed item it records the ask,
+makes the one model call itself with the owner's NEAR AI key (an OutLayer secret), checks and scores the signed answer
+and records it final; a second ask returns the recorded answer. No question, answer or response body leaves the enclave:
+the owner gets each answer's hashes, score and signature, and the aggregate task attests the run's roots and total.
+"""
+
+import hashlib
+import json
+from pathlib import Path
+
+import requests
+
+from fuin import core, owner, tee
+from fuin import policy as P
+
+
+def askers() -> list[dict]:
+    return tee.tee_policy().get("askers", [])
+
+
+def asker_for(policy: dict) -> dict:
+    a = policy["audit"]
+    found = [x for x in askers() if x["wasm_sha256"] == a["asker_wasm_sha256"] and x["project"] == a["asker_project"]]
+    if not found:
+        raise SystemExit(f"the round sealed asker {a['asker_wasm_sha256'][:12]}… in {a['asker_project']}, which policy/tee-v2.json doesn't list")
+    return found[0]
+
+
+def secrets_ref(st: dict) -> dict:
+    return {"profile": "nearai", "account_id": st["owner"]}
+
+
+def keygen(owner_id: str, ak: dict) -> dict:
+    """The asker's in-enclave key for this owner (sealed under the project's key: only the locked project's code opens it)."""
+    # one per (owner, build, project): the secret is sealed under the project's key, so another project can't open it
+    path = Path("private") / f"ask-key-{owner_id}-{ak['wasm_sha256'][:12]}-{ak['project'].replace('/', '_')}.json"
+    if path.exists():
+        return json.loads(path.read_text())
+    tx, input_data, out = tee.execute(owner_id, {"mode": "keygen"}, ak, project=ak["project"])
+    if "pub" not in out:
+        raise RuntimeError(f"asker keygen failed: {out}")
+    key = {"owner": owner_id, "wasm_sha256": ak["wasm_sha256"], "project": ak["project"], "pub": out["pub"], "sealed": out["sealed"],
+           "transaction_hash": tx}
+    path.write_text(json.dumps(key, indent=1))
+    return key
+
+
+def plaintext(st: dict, model: str, rn: dict) -> dict:
+    """The sealed round as the asker reads it: tee.plaintext's fields without rows (the enclave makes them)."""
+    return {"v": "fuin-tee-round-v1", "model": model, "policy_jcs": core.jcs(st["policy"]).decode(),
+            **({"seal_block_hash": st["seal"]["block_hash"]} if P.is_seal_bound(st["policy"]) else {}),
+            **({"model_pub": tee._signer_pub(rn).hex()} if P.is_e2ee(st["policy"]) else {}),
+            "items": [{"salt": r["salt"], "item_jcs": core.jcs(r["item"]).decode()} for r in st["items"]]}
+
+
+def _check_item(out: dict, st: dict, model: str, i: int, signer: str) -> dict:
+    """An ask's output, checked before it is kept: this round, this item, this signer, a valid provider_tee signature."""
+    from eth_account import Account
+    from eth_account.messages import encode_defunct
+    if out.get("v") != "fuin-ask-item-v1" or (out.get("model"), out.get("i"), out.get("benchmark_root")) != (model, i, st["seal"]["root"]):
+        raise RuntimeError(f"item {i}: unexpected asker output {str(out)[:200]}")
+    text = f"{model}:{out['req_sha256']}:{out['resp_sha256']}"
+    who = Account.recover_message(encode_defunct(text=text), signature=out["signature"]).lower()
+    if who != signer or str(out["signing_address"]).lower() != signer or out["score"] not in (0, 1):
+        raise RuntimeError(f"item {i}: signature doesn't recover to the preflighted signer")
+    return {"i": i, "req_sha256": out["req_sha256"], "resp_sha256": out["resp_sha256"], "score": out["score"],
+            "unreadable": bool(out.get("unreadable")), "attempts": out.get("attempts"),
+            "signature": {"text": text, "signature": out["signature"], "signing_address": out["signing_address"],
+                          "signature_kind": "provider_tee", "signing_algo": "ecdsa"}}
+
+
+def run(bid: str, model: str, host, tries: int = 3) -> dict:
+    """Ask every item of this model's run inside the enclave, then have the enclave attest the run (aggregate)."""
+    st = owner.load(bid)
+    if not P.is_asked_round(st["policy"]):
+        raise SystemExit("not an enclave-asked round (seal it with --ask)")
+    if "seal" not in st:
+        raise SystemExit("round not sealed yet")
+    ak = asker_for(st["policy"])
+    rn = owner.preflight(st, model)
+    if "commit" in rn:
+        raise SystemExit(f"{model} run already committed")
+    key = keygen(st["owner"], ak)
+    blob, eph_pub, nonce = tee.encrypt(tee.jdump(plaintext(st, model, rn)).encode(), key["pub"])
+    url, encoding, cleanup = host(blob)  # one hosted ciphertext for every ask and the aggregate; deleted at the end
+    try:
+        served = requests.get(url, timeout=120).content
+        base = {"url": url, "blob_sha256": hashlib.sha256(served).hexdigest(), "encoding": encoding, "sealed": key["sealed"],
+                "eph_pub": eph_pub, "nonce": nonce}
+        done = {r["i"] for r in rn["rows"]}
+        for i in range(len(st["items"])):
+            if i in done:
+                continue
+            for attempt in range(tries):  # a pending ask (nothing left the enclave) may be retried; the enclave counts it
+                try:
+                    tx, _, out = tee.execute(st["owner"], {"mode": "ask", **base, "i": i, "signer": rn["signer"]}, ak,
+                                             project=ak["project"], secrets_ref=secrets_ref(st))
+                    if "error" in out:
+                        raise RuntimeError(out["error"])
+                    row = _check_item(out, st, model, i, rn["signer"])
+                    row["ask_tx"] = tx
+                    break
+                except RuntimeError as e:
+                    rn["attempt_log"].append({"i": i, "attempt": attempt, "error": str(e)[:200]})
+                    owner.save(st)
+                    print(f"  {i}: attempt {attempt + 1} failed: {str(e)[:120]}", flush=True)
+            else:
+                raise SystemExit(f"item {i}: {tries} asks failed; rerun `fuin ask` to resume (a recorded answer is never re-asked)")
+            rn["rows"].append(row)
+            owner.save(st)
+            print(f"  {i}: score {row['score']} (attempt {row['attempts']})", flush=True)
+        tx, input_data, out = tee.execute(st["owner"], {"mode": "aggregate", **base}, ak, project=ak["project"])
+    finally:
+        if cleanup:
+            cleanup()
+    want = expected(st, model, rn)
+    diff = {k: (out.get(k), v) for k, v in want.items() if out.get(k) != v}
+    if out.get("v") != "fuin-tee-asked-v1" or diff:
+        raise RuntimeError(f"asker aggregate differs from the asked rows: {out.get('error') or diff}")
+    rn["tee_asked"] = {"v": "fuin-tee-asked-evidence-v1", "transaction_hash": tx, "input_data": input_data, "output": out,
+                       "record": tee.fetch_record(tx), "scorer_url": ak["url"]}
+    owner.save(st)
+    rn["tee_asked_check"] = check(st, model, host)
+    owner.save(st)
+    return st
+
+
+def check(st: dict, model: str, host) -> dict:
+    """Have the scorer rebuild every request of the asked run with the true seal block hash (mode asked-check): each must
+    equal the request the model signed, so every recorded ask came after the seal, and the roots must equal the run's."""
+    rn = st["runs"][model]
+    tp = tee.tee_policy()
+    sc = next(x for x in reversed(tp["scorers"]) if x["wasm_sha256"] in tp.get("asked_checkers", []))
+    rows = sorted(rn["rows"], key=lambda r: r["i"])
+    plain = {**plaintext(st, model, rn), "signer": rn["signer"],
+             "asked": [{"req_sha256": r["req_sha256"], "resp_sha256": r["resp_sha256"], "score": r["score"]} for r in rows]}
+    tx, input_data, out = tee._sealed_task(st["owner"], host, sc, "asked-check", plain)
+    want = {k: v for k, v in expected(st, model, rn).items() if k not in ("retried", "unreadable")}
+    diff = {k: (out.get(k), v) for k, v in want.items() if out.get(k) != v}
+    if out.get("v") != "fuin-tee-asked-check-v1" or diff:
+        raise RuntimeError(f"asked-check differs from the asked run: {out.get('error') or diff}")
+    return {"v": "fuin-tee-asked-check-evidence-v1", "transaction_hash": tx, "input_data": input_data, "output": out,
+            "record": tee.fetch_record(tx), "scorer_url": sc["url"]}
+
+
+def expected(st: dict, model: str, rn: dict) -> dict:
+    """What a faithful aggregate must output, from the asked rows (the commit uses the same rows)."""
+    rows = sorted(rn["rows"], key=lambda r: r["i"])
+    bl = owner.benchmark_leaves(st)
+    rl = [core.run_leaf(r["i"], bl[r["i"]], bytes.fromhex(r["req_sha256"]), bytes.fromhex(r["resp_sha256"]), r["score"]) for r in rows]
+    out = {"model": model, "n": len(st["items"]), "total": sum(r["score"] for r in rows), "benchmark_root": st["seal"]["root"],
+           "policy_hash": P.policy_hash(st["policy"]), "run_root": core.merkle_root(rl).hex(), "signer": rn["signer"],
+           "retried": sum(max(0, (r.get("attempts") or 1) - 1) for r in rows)}
+    if P.is_seal_bound(st["policy"]):
+        out["seal_block_hash"] = st["seal"]["block_hash"]
+    if P.is_e2ee(st["policy"]):
+        out["unreadable"] = sum(1 for r in rows if r.get("unreadable"))
+    return out

fuin/attestation.py

@@ -0,0 +1,235 @@
+"""Model attestation report checks (spec: Attestation acceptance policy).
+
+Credential-free: needs network access to Intel PCS (quote collateral) and NVIDIA NRAS (GPU verdict).
+"""
+
+import asyncio
+import base64
+import hashlib
+import inspect
+import json
+import time
+import re
+import struct
+
+import dcap_qvl
+import requests
+
+NRAS_URL = "https://nras.attestation.nvidia.com/v3/attest/gpu"
+CATALOG_URL = "https://cloud-api.near.ai/v1/model/list"
+IMAGE_RE = re.compile(r"image:\s*\S*?([a-z0-9][\w./-]*@sha256:[0-9a-f]{64})")
+
+
+def _json(v):
+    return json.loads(v) if isinstance(v, str) else v
+
+
+def app_compose(report: dict) -> str:
+    return _json(report["info"])["tcb_info"]["app_compose"]
+
+
+def compose_hash(report: dict) -> str:
+    return hashlib.sha256(app_compose(report).encode()).hexdigest()
+
+
+def image_digests(report: dict) -> list[str]:
+    compose = _json(app_compose(report))
+    return sorted(set(IMAGE_RE.findall(compose.get("docker_compose_file", ""))))
+
+
+def replay_rtmr3(event_log) -> bytes:
+    rtmr = bytes(48)
+    for ev in _json(event_log):
+        if ev.get("imr") != 3:
+            continue
+        digest = hashlib.sha384(
+            struct.pack("<I", ev["event_type"]) + b":" + ev["event"].encode() + b":" + bytes.fromhex(ev["event_payload"])
+        ).digest()
+        if ev.get("digest") and bytes.fromhex(ev["digest"]) != digest:
+            raise ValueError("event log digest mismatch")
+        rtmr = hashlib.sha384(rtmr + digest).digest()
+    return rtmr
+
+
+def parse_report_data(report_data: bytes) -> tuple[bytes, bytes]:
+    """64 bytes: signer (20-byte address, zero-padded to 32) || 32-byte client nonce."""
+    if len(report_data) != 64:
+        raise ValueError("report data must be 64 bytes")
+    return report_data[:32], report_data[32:]
+
+
+async def _collateral(quote: bytes):
+    r = dcap_qvl.get_collateral(dcap_qvl.INTEL_PCS_URL, quote)
+    return await r if inspect.isawaitable(r) else r
+
+
+def _pcs_reachable() -> bool:
+    try:
+        requests.get(f"{dcap_qvl.INTEL_PCS_URL.rstrip('/')}/tdx/certification/v4/qe/identity", timeout=15)
+        return True
+    except requests.RequestException:
+        return False
+
+
+def verify_quote(quote_hex: str):
+    """Returns (status, advisory_ids, td_report dict).
+
+    Raises ValueError/TypeError for a malformed or invalid quote, and RuntimeError when Intel's collateral can't be
+    fetched for a well-formed quote: an outage, not evidence of tampering. (The combined dcap call raised ValueError
+    for both, so an Intel outage was refused as an invalid quote.)"""
+    raw = bytes.fromhex(quote_hex)
+    dcap_qvl.parse_quote(raw)
+    for attempt in (1, 2):  # one retry: a single dropped request to Intel would otherwise read as an outage (the pilot hit one)
+        try:
+            collateral = asyncio.run(_collateral(raw))
+            break
+        except ValueError as e:  # an outage only if the request failed or Intel doesn't answer; otherwise the quote is at fault
+            dropped = any(m in str(e) for m in ("error sending request", "timed out", "dns error"))
+            if dropped and attempt == 1:
+                time.sleep(3)
+                continue
+            if dropped or not _pcs_reachable():
+                raise RuntimeError(f"Intel collateral unavailable: {str(e)[:160]}") from e
+            raise ValueError(f"quote rejected at the collateral step: {str(e)[:160]}") from e
+    res = dcap_qvl.verify(raw, collateral, int(time.time()))
+    rep = json.loads(res.to_json())["report"]
+    td = rep.get("TD10") or rep.get("TD15")
+    if td is None:
+        raise ValueError("not a TDX quote")
+    return res.status, list(res.advisory_ids), td
+
+
+NRAS_ISSUER = "https://nras.attestation.nvidia.com"
+NRAS_JWKS = "https://nras.attestation.nvidia.com/.well-known/jwks.json"
+_NRAS_KEYS: dict = {}  # NVIDIA's signing keys by kid, fetched once per process
+
+
+def _b64u(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _nras_key(kid: str):
+    """NVIDIA's ES384 (P-384) public key for this kid, from its published key set."""
+    from cryptography.hazmat.primitives.asymmetric import ec
+    if kid not in _NRAS_KEYS:
+        r = requests.get(NRAS_JWKS, timeout=30)
+        r.raise_for_status()
+        for k in r.json().get("keys", []):
+            if k.get("kty") == "EC" and k.get("crv") == "P-384":
+                _NRAS_KEYS[k["kid"]] = ec.EllipticCurvePublicNumbers(
+                    int.from_bytes(_b64u(k["x"]), "big"), int.from_bytes(_b64u(k["y"]), "big"), ec.SECP384R1()).public_key()
+    return _NRAS_KEYS.get(kid)
+
+
+def nras_token_ok(jwt: str, nonce: str, now: float | None = None) -> bool:
+    """NVIDIA's verdict token: ES384-signed by a key in NVIDIA's key set, issued by NRAS, inside its validity window,
+    bound to this report's nonce (eat_nonce), with an explicit overall pass (review 5)."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import ec, utils
+    try:
+        h64, c64, s64 = jwt.split(".")
+        header, claims, sig = json.loads(_b64u(h64)), json.loads(_b64u(c64)), _b64u(s64)
+    except ValueError:
+        return False
+    key = _nras_key(header.get("kid", "")) if header.get("alg") == "ES384" else None
+    if key is None or len(sig) != 96:
+        return False
+    try:
+        key.verify(utils.encode_dss_signature(int.from_bytes(sig[:48], "big"), int.from_bytes(sig[48:], "big")),
+                   f"{h64}.{c64}".encode(), ec.ECDSA(hashes.SHA384()))
+    except InvalidSignature:
+        return False
+    now = time.time() if now is None else now
+    return (claims.get("iss") == NRAS_ISSUER and claims.get("nbf", 0) <= now + 300 and claims.get("exp", 0) >= now - 300
+            and str(claims.get("eat_nonce", "")).lower() == nonce.lower() and claims.get("x-nvidia-overall-att-result") is True)
+
+
+def nras_verdict(nvidia_payload, nonce: str | None = None) -> bool:
+    """POST the GPU evidence unchanged to NVIDIA NRAS; True only on a verified overall pass for this nonce (the
+    evidence's own nonce unless given)."""
+    body = nvidia_payload if isinstance(nvidia_payload, str) else json.dumps(nvidia_payload)
+    r = requests.post(NRAS_URL, data=body, headers={"Content-Type": "application/json"}, timeout=60)
+    r.raise_for_status()
+    return nras_token_ok(r.json()[0][1], nonce if nonce is not None else str(_json(nvidia_payload).get("nonce", "")))
+
+
+def tcb_outcome(status: str, advisories: list[str]) -> str:
+    """User's TCB policy (2026-10-27): clean / warning / revoked."""
+    if status == "Revoked":
+        return "revoked"
+    return "clean" if status == "UpToDate" and not advisories else "warning"
+
+
+def check_report(report: dict, nonce_hex: str, policy: dict, *, use_nras: bool = True) -> dict:
+    """Check one model report under an attestation policy. Returns per-check results and an outcome.
+
+    outcome: "accepted", "accepted_with_warning", ("refused", code) or ("cant_certify", code).
+    """
+    if not all(isinstance(report.get(k), str) for k in ("model_name", "signing_address", "intel_quote")):
+        # NEAR also serves models from partners' own TEEs (Chutes, Tinfoil) with their own evidence format; Fūin checks only NEAR's
+        return {"model": report.get("model_name") or report.get("model"), "signing_address": str(report.get("signing_address", "")).lower(),
+                "error": f"attested by {report.get('provider') or 'another scheme'}, in a format Fūin doesn't verify",
+                "outcome": ("cant_certify", "policy_unsupported")}
+    checks: dict = {"model": report["model_name"], "signing_address": report["signing_address"].lower()}
+    nonce = nonce_hex.lower()
+    try:
+        status, advisories, td = verify_quote(report["intel_quote"])
+    except (ValueError, KeyError, TypeError) as e:
+        return {**checks, "error": str(e), "outcome": ("refused", "attestation_invalid")}
+    except RuntimeError as e:  # collateral service unreachable
+        return {**checks, "error": str(e), "outcome": ("cant_certify", "evidence_unavailable")}
+    signer_rd, nonce_rd = parse_report_data(bytes.fromhex(td["report_data"]))
+    signer = bytes.fromhex(report["signing_address"].removeprefix("0x"))
+    checks.update(
+        quote_status=status,
+        advisories=advisories,
+        signing_algo_ok=report.get("signing_algo") == "ecdsa",
+        report_data_signer_ok=signer_rd == signer.ljust(32, b"\0"),
+        report_data_nonce_ok=nonce_rd.hex() == nonce,
+        request_nonce_ok=str(report.get("request_nonce", "")).lower() == nonce,
+        debug_off=int(td["td_attributes"][:2], 16) & 1 == 0,
+        mrconfigid_ok=bytes.fromhex(td["mr_config_id"]) == b"\x01" + bytes.fromhex(compose_hash(report)) + bytes(15),
+        gpu_nonce_ok=str(_json(report["nvidia_payload"]).get("nonce", "")).lower() == nonce,
+    )
+    try:
+        checks["rtmr3_ok"] = replay_rtmr3(report["event_log"]).hex() == td["rt_mr3"]
+    except ValueError:
+        checks["rtmr3_ok"] = False
+    bad = [k for k, v in checks.items() if k.endswith(("_ok", "_off")) and v is not True]
+    if bad:
+        return {**checks, "failed": bad, "outcome": ("refused", "attestation_invalid")}
+    tcb = tcb_outcome(status, advisories)
+    if tcb == "revoked":
+        return {**checks, "outcome": ("refused", "tcb_revoked")}
+    accepted = policy.get("models", {}).get(report["model_name"], {}).get("compose_hashes", {})
+    checks["compose_hash"] = compose_hash(report)
+    if checks["compose_hash"] not in accepted:
+        return {**checks, "outcome": ("cant_certify", "measurement_unapproved")}
+    # the OS the application runs on (firmware, kernel, initrd, cmdline) must be an approved measurement too; MRCONFIGID and
+    # RTMR3 only identify the application, and an unapproved OS could fake those extends
+    entry = accepted[checks["compose_hash"]]
+    os_seen = {k: td[k] for k in ("mr_td", "rt_mr0", "rt_mr1", "rt_mr2")}
+    checks["os_approved"] = (os_seen in entry.get("os_measurements", [])
+                             and (report.get("info") or {}).get("os_image_hash") == entry.get("os_image_hash"))
+    if not checks["os_approved"]:
+        return {**checks, "os_seen": os_seen, "outcome": ("cant_certify", "measurement_unapproved")}
+    if use_nras:
+        try:
+            checks["nras_ok"] = nras_verdict(report["nvidia_payload"], nonce)
+        except (requests.RequestException, ValueError, KeyError, IndexError) as e:
+            return {**checks, "error": f"NRAS: {e}", "outcome": ("cant_certify", "evidence_unavailable")}
+        if not checks["nras_ok"]:
+            return {**checks, "outcome": ("refused", "attestation_invalid")}
+    checks["tcb"] = tcb
+    return {**checks, "td": td, "outcome": ("accepted",) if tcb == "clean" else ("accepted_with_warning",)}
+
+
+def is_tee_model(model_id: str, catalog: dict | None = None) -> bool:
+    """Catalog says verifiable + attestationSupported; external models (OpenAI, Anthropic, ...) don't."""
+    catalog = catalog or requests.get(CATALOG_URL, timeout=30).json()
+    for m in catalog["models"]:
+        if m.get("modelId") == model_id:
+            md = m.get("metadata", {})
+            return bool(md.get("verifiable") and md.get("attestationSupported"))
+    return False

fuin/cli.py

@@ -0,0 +1,220 @@
+"""fuin: check | seal | run | commit | close | reveal | status (owner) and verify | show (anyone, no credentials)."""
+
+import argparse
+import base64
+import hashlib
+import json
+import sys
+
+from fuin import diagnose, owner, tooling, verify
+
+QWEN = "Qwen/Qwen3.8-27B"
+SETTINGS = {"max_tokens": 4096, "temperature": 0}  # user, Nov 3: both models reason, 4096-token cap
+
+
+def _print_verdict(path: str, res: dict) -> None:
+    head = {"VERIFIED": "VERIFIED", "REFUSED": f"REFUSED {res.get('code')}", "CANT_CERTIFY": f"CAN'T CERTIFY {res.get('code')}"}
+    print(f"{path}: {head[res['outcome']]}")
+    for name, status, detail in res["checks"]:
+        print(f"  [{status}] {name}: {detail}")
+    if res.get("detail"):
+        print(f"  detail: {res['detail']}")
+    if res["outcome"] == "VERIFIED":
+        print(f"  scope: {res['scope']}")
+        for w in res["warnings"]:
+            print(f"  warning: {w}")
+        print("  limits:")
+        for lim in res["limits"]:
+            print(f"   - {lim}")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="fuin")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("seal"); s.add_argument("suite"); s.add_argument("--id", required=True)
+    s.add_argument("--owner", required=True); s.add_argument("--model", action="append", default=None)
+    s.add_argument("--max-tokens", type=int, default=SETTINGS["max_tokens"], help="sealed per-model token cap (reasoning included)")
+    s.add_argument("--tee", action="store_true", help="zero-reveal round: every item scored inside OutLayer's TEE by the current "
+                   "pinned scorer build (sealed in the policy), requests bound to the seal block, nothing revealed")
+    s.add_argument("--e2ee", action="store_true", help="request template v3: each question and answer end-to-end encrypted "
+                   "between you and the model's attested TEE key, so NEAR's gateway never sees them; requests bound to the seal block")
+    s.add_argument("--ask", action="store_true", help="zero-reveal round whose model calls are made inside OutLayer's TEE by the "
+                   "current pinned asker build in its locked project, each item asked once (sealed in the policy); run `fuin ask`")
+    for c in ("run", "commit"):
+        p = sub.add_parser(c); p.add_argument("--id", required=True); p.add_argument("--model", default=QWEN)
+        if c == "run":
+            p.add_argument("--parallel", type=int, default=1, help="questions in flight at once (rows are still saved in order)")
+    p = sub.add_parser("close"); p.add_argument("--id", required=True)
+    p = sub.add_parser("reveal"); p.add_argument("--id", required=True); p.add_argument("--out", default="examples")
+    p = sub.add_parser("verify"); p.add_argument("certs", nargs="+"); p.add_argument("--json", action="store_true")
+    p = sub.add_parser("check", help="validate a suite and the prerequisites before sealing"); p.add_argument("suite")
+    p.add_argument("--owner"); p.add_argument("--model", action="append", default=None)
+    p.add_argument("--tee", action="store_true", help="state the disclosure for a zero-reveal (TEE-scored) round")
+    p = sub.add_parser("status", help="show where a round stands and the next command"); p.add_argument("--id", required=True)
+    p.add_argument("--out", default="examples", help="where the round's certificates were written (the --out of reveal or tee-score)")
+    p = sub.add_parser("show"); p.add_argument("cert"); p.add_argument("--audit", action="store_true")
+    p = sub.add_parser("policy-update", help="draft the next attestation policy from fresh reports when NEAR redeploys a model "
+                       "(needs a key; writes policy/attestation-v<N+1>.json for review, approves nothing)")
+    p.add_argument("--model", action="append", default=None, help="model to check (default: every model in the current policy)")
+    p = sub.add_parser("tee-key", help="make the TEE scorer's in-enclave key for this owner (once per scorer build)")
+    p.add_argument("--owner", required=True)
+    p = sub.add_parser("tee-score", help="re-score a committed run inside OutLayer's TEE and add the evidence to its certificate")
+    p.add_argument("--id", required=True); p.add_argument("--model", required=True); p.add_argument("--out", default="examples")
+    p.add_argument("--host", required=True, choices=["fastfs", "gist"],
+                   help="where the encrypted run is hosted for the scorer: fastfs (permanent, public) or gist (secret, deleted after)")
+    p = sub.add_parser("tee-ground", help="check every answer key against its cited near/docs line inside OutLayer's TEE (once per round)")
+    p.add_argument("--id", required=True); p.add_argument("--out", default="examples")
+    p.add_argument("--host", required=True, choices=["fastfs", "gist"],
+                   help="where the encrypted items are hosted for the enclave: fastfs (permanent, public) or gist (secret, deleted after)")
+    p = sub.add_parser("ask", help="enclave-asked round: ask every item inside the TEE, then have it attest the run")
+    p.add_argument("--id", required=True); p.add_argument("--model", required=True)
+    p.add_argument("--host", required=True, choices=["fastfs", "gist"], help="where the encrypted round is hosted for the asker")
+    p = sub.add_parser("ask-check", help="enclave-asked round: have the TEE rebuild every request with the true seal block hash")
+    p.add_argument("--id", required=True); p.add_argument("--model", required=True); p.add_argument("--out", default="examples")
+    p.add_argument("--host", required=True, choices=["fastfs", "gist"])
+    a = ap.parse_args(argv)
+
+    if a.cmd == "check":
+        return tooling.print_check(a.suite, a.owner, a.model or [QWEN], tee=a.tee)
+    if a.cmd == "status":
+        print("\n".join(tooling.status(a.id, a.out)))
+        return 0
+    held = owner.lock(a.id) if a.cmd in ("run", "commit", "close", "tee-score", "tee-ground", "reveal", "ask", "ask-check") else None  # noqa: F841 (held until exit)
+    if a.cmd == "seal":
+        res = tooling.check_suite(a.suite)
+        if res["errors"]:  # a seal can't be undone: refuse a broken suite
+            print("Not sealing: the suite has errors. Run `fuin check` for details.\n" + "\n".join("  ✗ " + e for e in res["errors"][:10]))
+            return 1
+        print(tooling.disclosure(res["n"], tee=a.tee or a.ask))
+        tee_wasm, ask_with = None, None
+        if a.tee and a.ask:
+            raise SystemExit("--tee and --ask are two kinds of zero-reveal round: pick one")
+        if a.tee:
+            from fuin import tee
+            tee_wasm = tee.tee_policy()["current"]
+        if a.ask:
+            from fuin import asker
+            if not asker.askers():
+                raise SystemExit("policy/tee-v2.json pins no asker build")
+            ask_with = (asker.askers()[-1]["wasm_sha256"], asker.askers()[-1]["project"])
+        owner.seal(a.suite, a.id, a.owner, {m: {**SETTINGS, "max_tokens": a.max_tokens} for m in (a.model or [QWEN])}, tee_wasm=tee_wasm,
+                   encrypt=a.e2ee, asker=ask_with)
+    elif a.cmd == "ask":
+        from fuin import asker, tee
+        st = owner.load(a.id)
+        host = tee.fastfs_host(st["owner"]) if a.host == "fastfs" else tee.gist_host
+        st = asker.run(a.id, a.model, host)
+        o = st["runs"][a.model]["tee_asked"]["output"]
+        print(f"every item asked once inside the TEE: {o['total']}/{o['n']}, {o['retried']} retried asks "
+              f"(aggregate tx {st['runs'][a.model]['tee_asked']['transaction_hash']}); next: fuin commit")
+    elif a.cmd == "ask-check":
+        from fuin import asker, tee
+        st = owner.load(a.id)
+        host = tee.fastfs_host(st["owner"]) if a.host == "fastfs" else tee.gist_host
+        ev = st["runs"][a.model]["tee_asked_check"] = asker.check(st, a.model, host)
+        owner.save(st)
+        print(f"every request rebuilt with the seal block's hash matches the signed one (task {ev['record']['task_id']})")
+        if st.get("close"):
+            for path in owner.reveal(a.id, a.out):
+                print(path)
+    elif a.cmd == "run":
+        owner.run(a.id, a.model, a.parallel)
+    elif a.cmd == "commit":
+        owner.commit(a.id, a.model)
+    elif a.cmd == "close":
+        owner.close(a.id)
+    elif a.cmd == "reveal":
+        for p in owner.reveal(a.id, a.out):
+            print(p)
+    elif a.cmd == "policy-update":
+        from fuin import policyupdate
+        draft, notes = policyupdate.propose(a.model or sorted(owner.attestation_policy()["models"]))
+        print("\n".join(notes))
+        if draft is None:
+            print("nothing new: every candidate is already approved or was not proposed")
+        else:
+            path = policyupdate.write(draft)
+            print(f"wrote {path} for review; the verifier keeps using {owner.ATTESTATION_POLICY.name} until "
+                  "owner.ATTESTATION_POLICY points at the reviewed file")
+    elif a.cmd == "tee-key":
+        from fuin import tee
+        k = tee.keygen(a.owner)
+        print(f"in-TEE key for {a.owner}: pub {k['pub']} (keygen tx {k['transaction_hash']})")
+    elif a.cmd == "tee-score":
+        from fuin import tee
+        st = owner.load(a.id)
+        if "commit" not in st["runs"].get(a.model, {}):
+            raise SystemExit(f"{a.model} run is not committed yet")
+        host = tee.fastfs_host(st["owner"]) if a.host == "fastfs" else tee.gist_host
+        ev = tee.score(st, a.model, st["owner"], host)
+        st["runs"][a.model]["tee_score"] = ev
+        owner.save(st)
+        print(f"TEE score {ev['output']['total']}/{ev['output']['n']} matches the commitment (tx {ev['transaction_hash']})")
+        from fuin import policy as P
+        waiting = [m for m, rn in st["runs"].items() if "commit" in rn and not rn.get("tee_score")]
+        if P.is_tee_round(st["policy"]) and waiting:  # a zero-reveal round's certificates need every run's TEE score
+            print(f"certificates are written once every run has its TEE score; still to score: {', '.join(waiting)}")
+        elif st.get("close"):  # a closed round's certificates are regenerated with the evidence; the sample is re-derived, unchanged
+            for p in owner.reveal(a.id, a.out):
+                print(p)
+    elif a.cmd == "tee-ground":
+        from fuin import policy as P, tee
+        st = owner.load(a.id)
+        if "seal" not in st:
+            raise SystemExit("round not sealed yet")
+        host = tee.fastfs_host(st["owner"]) if a.host == "fastfs" else tee.gist_host
+        st["tee_ground"] = ev = tee.ground(st, st["owner"], host)
+        owner.save(st)
+        o = ev["output"]
+        print(f"answer keys grounded in the TEE: {o['n'] - o['flagged']}/{o['n']} appear in their cited line; "
+              f"{o['flagged']} flagged (tx {ev['transaction_hash']})")
+        if st.get("close") and all("commit" not in rn or rn.get("tee_score") or rn.get("tee_asked") or not P.is_tee_round(st["policy"]) for rn in st["runs"].values()):
+            for path in owner.reveal(a.id, a.out):  # certificates regenerated with the grounding; nothing else changes
+                print(path)
+    elif a.cmd == "verify":
+        outcomes = set()
+        for path in a.certs:
+            raw = b""
+            try:
+                raw = open(path, "rb").read()
+                cert = json.loads(raw.decode("utf-8"))
+            except (OSError, ValueError) as e:
+                res = {"outcome": "REFUSED", "code": "certificate_invalid", "detail": str(e), "checks": []}
+            else:
+                res = verify.verify(cert)
+            # the file's hash ties a recorded result to these exact bytes (scripts/build_page.py refuses a mismatch)
+            print(json.dumps({"cert": path, "cert_sha256": hashlib.sha256(raw).hexdigest(), **res}, default=list)) if a.json else _print_verdict(path, res)
+            outcomes.add(res["outcome"])
+        return 1 if "REFUSED" in outcomes else 2 if "CANT_CERTIFY" in outcomes else 0  # REFUSED outranks CAN'T CERTIFY
+    elif a.cmd == "show":
+        cert = json.loads(open(a.cert, encoding="utf-8").read())
+        b, r, au = cert["benchmark"], cert["run"], cert["audit"]
+        print(f"{b['id']} · {r['model_id']} run {r['run_index']} · committed total {r['total_score']}/{b['n']}")
+        from fuin import policy as P
+        if P.is_tee_round(b["policy"]):
+            print(f"audit: none · a TEE-scored round reveals nothing: all {b['n']} items stay private and were re-scored inside "
+                  f"OutLayer's TEE by scorer {b['policy']['audit']['scorer_wasm_sha256'][:12]}… (fuin verify checks that evidence)")
+            return 0
+        print(f"audit: D={au['D']} k={au['k']} (target 95%) · revealed {au['k']} of {b['n']}, unrevealed {b['n'] - au['k']}")
+        print(f"settings: {b['policy']['models'][r['model_id']]} · scorer {b['policy']['scorer']['name']}")
+        items = {it["i"]: it for it in r["items"]}
+        rows = []
+        for x in au["reveals"]:
+            resp = json.loads(base64.b64decode(x["response_b64"]))
+            ch = resp["choices"][0]
+            rows.append((x, ch.get("finish_reason"), (ch["message"].get("content") or "").strip()))
+        cut = sum(f == "length" for _, f, _ in rows)
+        right = sum(items[x["i"]]["score"] for x, _, _ in rows)
+        print(f"revealed sample: {right}/{len(rows)} correct; {cut}/{len(rows)} cut off at max_tokens (scored 0) — checkable from the revealed bytes")
+        bd = diagnose.breakdown(cert)
+        print(f"revealed misses: {bd['wrong']} wrong, {bd['format']} format (right value, rejected form), {bd['cut off']} cut off — a reading aid, not a score")
+        if a.audit:
+            for x, fin, content in rows:
+                said = "(cut off before answering)" if fin == "length" and not content else repr(content[:50])
+                print(f"  #{x['i']:>2} score {items[x['i']]['score']} · Q: {x['item']['question']}\n       expected {x['item']['answer']!r} · model said {said}"
+                      f" · source {x['item'].get('source', {}).get('url', '-')}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())