contracts: Receipt v1 schema, canonicalization, verify rules, test vectors

2025-12-26 23:13:34 +00:00
commit a43526f768
7 changed files with 299 additions and 0 deletions
--- a/receipt_v1.schema.json
+++ b/receipt_v1.schema.json
@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://vm/contracts/receipt_v1.schema.json",
+  "title": "VaultMesh Receipt v1",
+  "description": "Operator-grade receipt envelope shared by vm-cloud, vaultmesh-mcp, command-center, civilization-ledger.",
+  "type": "object",
+  "properties": {
+    "receipt_version": { "type": "string", "const": "1" },
+    "created_at": { "type": "string", "format": "date-time" },
+    "source": { "type": "string", "description": "Emitter identity, e.g., vmc, mcp, command-center" },
+    "action": { "type": "string" },
+    "reason": { "type": "string" },
+
+    "target": {
+      "type": "object",
+      "properties": {
+        "id": { "type": ["string", "number" ] },
+        "name": { "type": "string" },
+        "ip": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+
+    "request": {
+      "type": "object",
+      "properties": {
+        "method": { "type": "string" },
+        "path": { "type": "string" },
+        "body": { }
+      },
+      "required": ["method", "path"],
+      "additionalProperties": false
+    },
+
+    "response": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "integer" },
+        "ok": { "type": "boolean" },
+        "data": { },
+        "raw": { "type": "string" }
+      },
+      "required": ["status", "ok", "raw"],
+      "additionalProperties": false
+    },
+
+    "prev_blake3": { "type": ["string", "null"], "description": "Chain link to previous receipt blake3" },
+    "hash_alg": { "type": "string", "const": "blake3+sha256" },
+    "blake3": { "type": "string" },
+    "sha256": { "type": "string" },
+
+    "plan_file": { "type": ["string", "null"] },
+    "plan_blake3": { "type": ["string", "null"] },
+    "plan_sha256": { "type": ["string", "null"] },
+
+    "lock_file": { "type": ["string", "null"] },
+    "lock_started_at": { "type": ["string", "null"] },
+    "force": { "type": "boolean" },
+
+    "cwd": { "type": "string" },
+    "user": { "type": "string" },
+    "hostname": { "type": "string" },
+    "argv": { "type": "array", "items": { "type": "string" } },
+
+    "sig_alg": { "type": "string", "enum": ["ed25519"] },
+    "signer_pub": { "type": "string" },
+    "signature": { "type": "string" },
+    "signed_at": { "type": "string", "format": "date-time" }
+  },
+  "required": [
+    "receipt_version",
+    "created_at",
+    "source",
+    "action",
+    "request",
+    "response",
+    "prev_blake3",
+    "hash_alg",
+    "blake3",
+    "sha256"
+  ],
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": { "properties": { "sig_alg": { "const": "ed25519" } }, "required": ["sig_alg"] },
+      "then": { "required": ["signer_pub", "signature"] }
+    }
+  ]
+}