veriguild 0.0.1__py3-none-any.whl

veriguild/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Veriguild draft protocol schemas (design phase)."""
+__version__ = "0.0.1"
+PROTOCOL_VERSION = "0.2-draft"

veriguild/cli.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal CLI: list bundled schemas and validate a JSON document against one."""
+import json
+import sys
+from importlib import resources
+
+from jsonschema import Draft202012Validator
+from referencing import Registry, Resource
+
+from . import PROTOCOL_VERSION, __version__
+
+
+def _schemas():
+    out = {}
+    for entry in resources.files("veriguild").joinpath("schemas").iterdir():
+        if entry.name.endswith(".schema.json"):
+            s = json.loads(entry.read_text())
+            out[entry.name[: -len(".schema.json")]] = s
+    return out
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    schemas = _schemas()
+    if not argv or argv[0] in ("-h", "--help"):
+        print(f"veriguild {__version__} (protocol {PROTOCOL_VERSION}, design phase)")
+        print("usage: veriguild schemas | veriguild validate <schema> <file.json>")
+        return 0
+    if argv[0] == "schemas":
+        print("\n".join(sorted(schemas)))
+        return 0
+    if argv[0] == "validate" and len(argv) == 3:
+        name, path = argv[1], argv[2]
+        if name not in schemas:
+            print(f"unknown schema: {name}", file=sys.stderr)
+            return 4
+        reg = Registry().with_resources([(s["$id"], Resource.from_contents(s)) for s in schemas.values()])
+        errs = list(Draft202012Validator(schemas[name], registry=reg).iter_errors(json.load(open(path))))
+        for e in errs:
+            print(f"error: {e.message}")
+        print("valid" if not errs else f"{len(errs)} error(s)")
+        return 0 if not errs else 1
+    print("usage: veriguild schemas | veriguild validate <schema> <file.json>", file=sys.stderr)
+    return 4
+
+
+if __name__ == "__main__":
+    sys.exit(main())

veriguild/schemas/agent-record.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/agent-record.schema.json",
+  "title": "AgentRecord predicate. metadata and ext are informational and never read by decide.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "$ref": "defs.schema.json#/$defs/version"
+    },
+    "agent": {
+      "$ref": "defs.schema.json#/$defs/did_key"
+    },
+    "operator_id": {
+      "$ref": "defs.schema.json#/$defs/operator_id"
+    },
+    "requested_modules": {
+      "type": "array",
+      "items": {
+        "$ref": "defs.schema.json#/$defs/module_name"
+      },
+      "uniqueItems": true
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "a2a_card_url": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 512
+        }
+      },
+      "required": []
+    },
+    "ext": {
+      "$ref": "defs.schema.json#/$defs/ext"
+    }
+  },
+  "required": [
+    "v",
+    "agent",
+    "operator_id",
+    "requested_modules"
+  ]
+}

veriguild/schemas/build-attestation.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/build-attestation.schema.json",
+  "title": "BuildAttestation predicate",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "$ref": "defs.schema.json#/$defs/version"
+    },
+    "binding": {
+      "$ref": "defs.schema.json#/$defs/binding"
+    },
+    "result": {
+      "$ref": "defs.schema.json#/$defs/result"
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "$ref": "defs.schema.json#/$defs/finding"
+      }
+    },
+    "log_digest": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "run_id": {
+      "$ref": "defs.schema.json#/$defs/nonce"
+    },
+    "node": {
+      "$ref": "defs.schema.json#/$defs/node_ref"
+    },
+    "recipe_digest": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "outputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "digest": {
+            "$ref": "defs.schema.json#/$defs/digest"
+          }
+        },
+        "required": [
+          "name",
+          "digest"
+        ]
+      }
+    },
+    "export_manifest_digest": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    }
+  },
+  "required": [
+    "v",
+    "binding",
+    "recipe_digest",
+    "result",
+    "findings",
+    "outputs",
+    "export_manifest_digest",
+    "log_digest",
+    "run_id",
+    "node"
+  ]
+}

veriguild/schemas/checkpoint.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/checkpoint.schema.json",
+  "title": "Checkpoint predicate. Cosignatures attest log consistency only, not decision correctness (P-50).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "$ref": "defs.schema.json#/$defs/version"
+    },
+    "ledger_head": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "seq": {
+      "$ref": "defs.schema.json#/$defs/seq"
+    },
+    "timestamp": {
+      "$ref": "defs.schema.json#/$defs/timestamp"
+    },
+    "c2sp_note_digest": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "cosignatures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "witness": {
+            "$ref": "defs.schema.json#/$defs/did_key"
+          },
+          "sig": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "witness",
+          "sig"
+        ]
+      }
+    }
+  },
+  "required": [
+    "v",
+    "ledger_head",
+    "seq",
+    "timestamp"
+  ]
+}

veriguild/schemas/contribution.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/contribution.schema.json",
+  "title": "Contribution predicate (P-23 to P-27)",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "$ref": "defs.schema.json#/$defs/version"
+    },
+    "repo": {
+      "$ref": "defs.schema.json#/$defs/repo"
+    },
+    "agent": {
+      "$ref": "defs.schema.json#/$defs/did_key"
+    },
+    "base_commit": {
+      "$ref": "defs.schema.json#/$defs/git_oid"
+    },
+    "head_commit": {
+      "$ref": "defs.schema.json#/$defs/git_oid"
+    },
+    "spec_version": {
+      "$ref": "defs.schema.json#/$defs/spec_version"
+    },
+    "modules": {
+      "type": "array",
+      "items": {
+        "$ref": "defs.schema.json#/$defs/module_name"
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "changed_paths_digest": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "nonce": {
+      "$ref": "defs.schema.json#/$defs/nonce"
+    },
+    "created_seq": {
+      "$ref": "defs.schema.json#/$defs/seq"
+    },
+    "message": {
+      "type": "string",
+      "maxLength": 4096
+    },
+    "ext": {
+      "$ref": "defs.schema.json#/$defs/ext"
+    }
+  },
+  "required": [
+    "v",
+    "repo",
+    "agent",
+    "base_commit",
+    "head_commit",
+    "spec_version",
+    "modules",
+    "changed_paths_digest",
+    "nonce",
+    "created_seq"
+  ]
+}

veriguild/schemas/cutoff-marker.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/cutoff-marker.schema.json",
+  "title": "Writer-signed evidence cutoff for evidence_wait = all-or-cutoff (P-32 step 9)",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "$ref": "defs.schema.json#/$defs/version"
+    },
+    "contribution_id": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "at_seq": {
+      "$ref": "defs.schema.json#/$defs/seq"
+    }
+  },
+  "required": [
+    "v",
+    "contribution_id",
+    "at_seq"
+  ]
+}

veriguild/schemas/decision-bundle.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/decision-bundle.schema.json",
+  "title": "Decision bundle manifest (P-39 to P-44). Bundle ID = Digest(JCS(manifest)). Items with role attestation MUST carry receipt_seq and class.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "v": {
+      "$ref": "defs.schema.json#/$defs/version"
+    },
+    "contribution_id": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "decision": {
+      "enum": [
+        "accept",
+        "reject",
+        "pending",
+        "blocked"
+      ]
+    },
+    "reasons": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^R[0-9]{3}$"
+      }
+    },
+    "decision_seq": {
+      "$ref": "defs.schema.json#/$defs/seq"
+    },
+    "ledger_view_entry": {
+      "$ref": "defs.schema.json#/$defs/digest"
+    },
+    "spec_version": {
+      "$ref": "defs.schema.json#/$defs/spec_version"
+    },
+    "base_commit": {
+      "$ref": "defs.schema.json#/$defs/git_oid"
+    },
+    "candidate_commit": {
+      "$ref": "defs.schema.json#/$defs/git_oid"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "role": {
+            "enum": [
+              "contribution",
+              "git-objects",
+              "policy-bundle",
+              "spec-objects",
+              "scope-manifest",
+              "attestation",
+              "resolution",
+              "cutoff",
+              "log",
+              "decision-report",
+              "previous-bundle"
+            ]
+          },
+          "digest": {
+            "$ref": "defs.schema.json#/$defs/digest"
+          },
+          "media_type": {
+            "type": "string"
+          },
+          "receipt_seq": {
+            "$ref": "defs.schema.json#/$defs/seq"
+          },
+          "class": {
+            "enum": [
+              "invalid",
+              "irrelevant",
+              "ineligible",
+              "inconclusive",
+              "pass",
+              "contradictory",
+              "fraudulent"
+            ]
+          }
+        },
+        "required": [
+          "role",
+          "digest",
+          "media_type"
+        ]
+      },
+      "minItems": 1
+    },
+    "writer": {
+      "$ref": "defs.schema.json#/$defs/node_ref"
+    }
+  },
+  "required": [
+    "v",
+    "contribution_id",
+    "decision",
+    "reasons",
+    "decision_seq",
+    "ledger_view_entry",
+    "spec_version",
+    "base_commit",
+    "candidate_commit",
+    "items",
+    "writer"
+  ]
+}

veriguild/schemas/defs.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/defs.schema.json",
+  "title": "Shared definitions",
+  "$defs": {
+    "version": {
+      "const": "0.2"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "did_key": {
+      "type": "string",
+      "pattern": "^did:key:z6Mk[1-9A-HJ-NP-Za-km-z]{44,48}$"
+    },
+    "git_oid": {
+      "type": "string",
+      "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$",
+      "description": "Git object ID (commit, tree or blob). 40 hex for SHA-1 repositories, 64 hex for SHA-256 repositories."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "timestamp": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
+    },
+    "module_name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+    },
+    "operator_id": {
+      "$ref": "#/$defs/digest"
+    },
+    "nonce": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$"
+    },
+    "repo": {
+      "type": "string",
+      "pattern": "^[a-z0-9.-]+/[A-Za-z0-9._/-]+$"
+    },
+    "rel_path": {
+      "type": "string",
+      "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$)).+$"
+    },
+    "spec_version": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "seq",
+        "spec_tree",
+        "policy_digest"
+      ],
+      "properties": {
+        "seq": {
+          "$ref": "#/$defs/seq"
+        },
+        "spec_tree": {
+          "$ref": "#/$defs/git_oid"
+        },
+        "policy_digest": {
+          "$ref": "#/$defs/digest"
+        }
+      }
+    },
+    "tool": {
+      "enum": [
+        "dafny",
+        "verus",
+        "lean"
+      ]
+    },
+    "result": {
+      "enum": [
+        "pass",
+        "fail",
+        "error",
+        "unknown"
+      ],
+      "description": "fail = definite verification failure attributed to the proof. error = crash, timeout or resource exhaustion. unknown = could not determine."
+    },
+    "ext": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^ext/[a-z0-9-]+$"
+      },
+      "description": "Informational only. MUST NOT be read by decide (P-26)."
+    },
+    "node_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "key",
+        "operator_id"
+      ],
+      "properties": {
+        "key": {
+          "$ref": "#/$defs/did_key"
+        },
+        "operator_id": {
+          "$ref": "#/$defs/operator_id"
+        }
+      }
+    },
+    "threshold_keys": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "threshold",
+        "keys"
+      ],
+      "properties": {
+        "threshold": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "keys": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/did_key"
+          }
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "line",
+        "construct",
+        "source"
+      ],
+      "properties": {
+        "path": {
+          "$ref": "#/$defs/rel_path"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "construct": {
+          "type": "string"
+        },
+        "source": {
+          "enum": [
+            "scanner",
+            "dafny-audit",
+            "axioms-check",
+            "binding-check"
+          ]
+        }
+      }
+    },
+    "binding": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Fields every attestation binds to (P-28 steps E5 to E8).",
+      "required": [
+        "repo",
+        "contribution_id",
+        "candidate_commit",
+        "spec_version",
+        "toolchain_digest",
+        "module",
+        "scope_manifest_digest"
+      ],
+      "properties": {
+        "repo": {
+          "$ref": "#/$defs/repo"
+        },
+        "contribution_id": {
+          "$ref": "#/$defs/digest"
+        },
+        "candidate_commit": {
+          "$ref": "#/$defs/git_oid"
+        },
+        "spec_version": {
+          "$ref": "#/$defs/spec_version"
+        },
+        "toolchain_digest": {
+          "$ref": "#/$defs/digest"
+        },
+        "module": {
+          "$ref": "#/$defs/module_name"
+        },
+        "scope_manifest_digest": {
+          "$ref": "#/$defs/digest"
+        }
+      }
+    }
+  }
+}

veriguild/schemas/dsse-envelope.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://veriguild.dev/schemas/v0.2/dsse-envelope.schema.json",
+  "title": "DSSE envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "payloadType": {
+      "const": "application/vnd.in-toto+json"
+    },
+    "payload": {
+      "type": "string",
+      "contentEncoding": "base64"
+    },
+    "signatures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "keyid": {
+            "$ref": "defs.schema.json#/$defs/did_key"
+          },
+          "sig": {
+            "type": "string",
+            "contentEncoding": "base64"
+          }
+        },
+        "required": [
+          "keyid",
+          "sig"
+        ]
+      },
+      "minItems": 1
+    }
+  },
+  "required": [
+    "payloadType",
+    "payload",
+    "signatures"
+  ]
+}