proof-aware-crypto-tooling-agent/notebooks/02_claim_cards_and_risk_model.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Lecture 2: Claim Cards and the R0-R5 Risk Model\n",
        "\n",
        "A claim card is a machine-readable assurance artifact. It records what was checked, what theorem names were involved, what axioms were observed, what exclusions remain, what trusted base is assumed, and what risk score follows.\n",
        "\n",
        "A claim card is not a marketing page. It is a structured input to policy.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Learning Objectives\n",
        "\n",
        "- Read the claim card schema.\n",
        "- Explain risk levels R0 through R5.\n",
        "- Generate an offline fixture claim card.\n",
        "- Understand why R3 can authorize lower-layer library use but not wallet construction.\n",
        "- Identify blockers and deployment constraints in a claim card.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Risk Levels\n",
        "\n",
        "- `R0`: Unknown or untrusted. No usable evidence.\n",
        "- `R1`: Tests, audits, or informal claims only.\n",
        "- `R2`: Formal model exists, but incomplete, weakly tied to production code, or major proof gaps remain.\n",
        "- `R3`: A specific lower-layer implementation artifact is Lean-checked for a specific backend and theorem boundary.\n",
        "- `R4`: End-to-end primitive proof covers public API, parsing/encoding, scalar arithmetic, hashing interface, signature equation, rejection rules, and implementation boundary.\n",
        "- `R5`: R4 plus reproducible production builds, compiler/build assurance, side-channel analysis, hardware/KMS/MPC integration, and operational controls.\n",
        "\n",
        "The expected first milestone for Ed25519 field plus Edwards arithmetic is R3 if certificates compile and the axiom audit is clean.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from pathlib import Path\n",
        "import sys\n",
        "\n",
        "repo_root = Path.cwd()\n",
        "if not (repo_root / \"src\" / \"pacta\").exists():\n",
        "    repo_root = repo_root.parent\n",
        "sys.path.insert(0, str(repo_root / \"src\"))\n",
        "\n",
        "from pacta.claims import build_claim_card\n",
        "from pacta.config import load_config\n",
        "\n",
        "config = load_config(repo_root / \"examples\" / \"repos.yaml\")\n",
        "repo = config.repo_named(\"dalek-ed25519-verified\")\n",
        "card = build_claim_card(repo, repo_root / \"repos\" / repo.name, offline_fixture=True)\n",
        "\n",
        "print(card[\"component\"])\n",
        "print(card[\"risk\"][\"level\"])\n",
        "print(card[\"risk\"][\"rationale\"])\n",
        "print(card[\"certificates\"][0])\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "important_fields = [\n",
        "    \"component\",\n",
        "    \"repo_url\",\n",
        "    \"repo_commit\",\n",
        "    \"verification_dir\",\n",
        "    \"kind\",\n",
        "    \"verified_backend\",\n",
        "    \"certificates\",\n",
        "    \"guarantees\",\n",
        "    \"preconditions\",\n",
        "    \"exclusions\",\n",
        "    \"trusted_base\",\n",
        "    \"evidence\",\n",
        "    \"risk\",\n",
        "]\n",
        "for field in important_fields:\n",
        "    print(field, \"=>\", type(card.get(field)).__name__)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Reading a Certificate Entry\n",
        "\n",
        "A certificate entry contains:\n",
        "\n",
        "- `name`: theorem or aggregate certificate name.\n",
        "- `status`: `proven`, `missing`, `failed`, or `unknown`.\n",
        "- `axiom_status`: `clean`, `dirty`, or `not_checked`.\n",
        "- `observed_axioms`: axioms reported by Lean.\n",
        "- `expected_axioms`: allowed standard axioms for this profile.\n",
        "\n",
        "A clean R3 result requires more than a theorem name. It requires a successful replay or trusted attestation, an expected axiom set, and no policy-blocking exclusions.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "for cert in card[\"certificates\"]:\n",
        "    print(f\"{cert['name']}: {cert['status']} / {cert['axiom_status']}\")\n",
        "    print(\"  observed:\", cert[\"observed_axioms\"])\n",
        "    print(\"  expected:\", cert[\"expected_axioms\"])\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Deployment Constraints\n",
        "\n",
        "Deployment constraints are where many assurance cases become honest. For Ed25519 arithmetic, constraints include:\n",
        "\n",
        "- Use exact pinned source or reviewed diff.\n",
        "- Use verified serial/u64 backend only.\n",
        "- Disable accelerator/syscall/hardware/SIMD paths unless separately certified.\n",
        "- Do not treat this as full EdDSA verification.\n",
        "- Keep key custody behind HSM/MPC/policy firewall until signing stack proof coverage improves.\n",
        "- Use ordinary tests/fuzzing at encoding/API/transaction boundaries.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "for constraint in card[\"risk\"][\"deployment_constraints\"]:\n",
        "    print(\"-\", constraint)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Exercises\n",
        "\n",
        "- Change the generated card in memory so one certificate is `missing`. Rescore it and explain the change.\n",
        "- Write a short policy that allows `build-library` at R3 but denies `build-wallet-demo` below R4.\n",
        "- Compare the trusted base for local replay versus third-party attestation.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from copy import deepcopy\n",
        "from pacta.risk import score_claim_card\n",
        "\n",
        "weaker = deepcopy(card)\n",
        "weaker[\"certificates\"][0][\"status\"] = \"missing\"\n",
        "weaker[\"certificates\"][0][\"axiom_status\"] = \"not_checked\"\n",
        "assessment = score_claim_card(weaker)\n",
        "print(assessment.level)\n",
        "print(assessment.rationale)\n",
        "print(assessment.blockers)\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "pygments_lexer": "ipython3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}