@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/run-statement.schema.json

@@ -0,0 +1,622 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/run-statement/v1/run-statement.schema.json",
+  "title": "chant workspace runs statement and verify output",
+  "description": "What `chant workspace runs statement <id> --signer <principal>` and `chant workspace runs verify [<id>] [--require signed] --json` print (#3192, ws-090): the agent-run statement for a signer whose key is elsewhere, and every stored statement judged offline against the runner keys `.chant/trust.json` lists at the base revision. Version 1 of the read contract. Readers ignore fields they do not know. The error codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/statementResult"
+    },
+    {
+      "$ref": "#/$defs/verifyResult"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "statementResult": {
+      "type": "object",
+      "description": "runs statement: what a signer signs. Sign the DSSE pre-authentication encoding of payloadType and the decoded payload, then store the envelope with runs sign <id> --envelope.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "run",
+        "payloadType",
+        "payload",
+        "statement"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/run-statement/v1/run-statement.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "verb": {
+          "const": "statement"
+        },
+        "run": {
+          "type": "string"
+        },
+        "payloadType": {
+          "const": "application/vnd.in-toto+json"
+        },
+        "payload": {
+          "type": "string",
+          "description": "Base64 of the statement's canonical JSON, the bytes to sign."
+        },
+        "statement": {
+          "$ref": "#/$defs/statement"
+        }
+      }
+    },
+    "verifyResult": {
+      "type": "object",
+      "description": "runs verify: each run's statements judged. Exit 0 unless --require signed finds an ended run that is not signed.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "trust",
+        "require",
+        "runs",
+        "summary",
+        "failures",
+        "ok"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/run-statement/v1/run-statement.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "verb": {
+          "const": "verify"
+        },
+        "trust": {
+          "$ref": "#/$defs/trust"
+        },
+        "require": {
+          "enum": [
+            "signed",
+            null
+          ]
+        },
+        "runs": {
+          "type": "array",
+          "description": "Newest first, by when each started.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "state",
+              "record",
+              "attestation"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "state": {
+                "enum": [
+                  "running",
+                  "ended"
+                ]
+              },
+              "record": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "sha256"
+                    ],
+                    "properties": {
+                      "sha256": {
+                        "type": "string",
+                        "pattern": "^[0-9a-f]{64}$"
+                      }
+                    }
+                  }
+                ],
+                "description": "The SHA-256 a statement signs: of the canonical JSON of [start line, end line]. Null until the run ends (#3192)."
+              },
+              "attestation": {
+                "$ref": "#/$defs/attestation"
+              }
+            }
+          }
+        },
+        "summary": {
+          "type": "object",
+          "required": [
+            "runs",
+            "signed",
+            "unsigned",
+            "failed",
+            "running"
+          ],
+          "properties": {
+            "runs": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "signed": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "unsigned": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "failed": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "running": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "failures": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Why --require signed fails. Empty without it: the report alone never fails."
+        },
+        "ok": {
+          "type": "boolean"
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing to judge. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/run-statement/v1/run-statement.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "verb": {
+          "enum": [
+            "statement",
+            "verify",
+            null
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "write-usage-invalid",
+                "run-unknown",
+                "run-not-ended"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "trust": {
+      "type": "object",
+      "description": "The trust policy the run statements are judged by, read at base.",
+      "required": [
+        "base",
+        "baseFrom",
+        "runners",
+        "problems"
+      ],
+      "properties": {
+        "base": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "baseFrom": {
+          "enum": [
+            "flag",
+            "origin/HEAD",
+            "main",
+            "master",
+            null
+          ]
+        },
+        "runners": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "principal",
+              "class"
+            ],
+            "properties": {
+              "principal": {
+                "type": "string"
+              },
+              "class": {
+                "enum": [
+                  "runner",
+                  "service"
+                ]
+              }
+            }
+          }
+        },
+        "problems": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Why the policy at base can't be read. Nothing verifies then."
+        }
+      }
+    },
+    "envelope": {
+      "type": "object",
+      "description": "A DSSE v1 envelope (https://github.com/secure-systems-lab/dsse).",
+      "required": [
+        "payloadType",
+        "payload",
+        "signatures"
+      ],
+      "properties": {
+        "payloadType": {
+          "type": "string"
+        },
+        "payload": {
+          "type": "string",
+          "description": "Base64 of the payload bytes."
+        },
+        "signatures": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "keyid",
+              "sig"
+            ],
+            "properties": {
+              "keyid": {
+                "type": "string",
+                "description": "The signing key's ssh fingerprint, SHA256:..."
+              },
+              "sig": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "statement": {
+      "type": "object",
+      "description": "An in-toto Statement v1 with chant's agent-run predicate (#3192, ws-090).",
+      "required": [
+        "_type",
+        "subject",
+        "predicateType",
+        "predicate"
+      ],
+      "properties": {
+        "_type": {
+          "const": "https://in-toto.io/Statement/v1"
+        },
+        "subject": {
+          "type": "array",
+          "description": "The commits the run made, sorted by id.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "digest"
+            ],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "The commit id."
+              },
+              "digest": {
+                "type": "object",
+                "required": [
+                  "gitCommit"
+                ],
+                "properties": {
+                  "gitCommit": {
+                    "type": "string"
+                  }
+                }
+              },
+              "annotations": {
+                "type": "object",
+                "properties": {
+                  "patchId": {
+                    "type": "string",
+                    "description": "git patch-id --stable of the commit."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "predicateType": {
+          "const": "https://intentius.io/chant/agent-run/v1"
+        },
+        "predicate": {
+          "type": "object",
+          "required": [
+            "signer",
+            "run",
+            "unit",
+            "harness",
+            "model",
+            "provider",
+            "by"
+          ],
+          "properties": {
+            "signer": {
+              "type": "string",
+              "description": "The runner principal whose key signs: the one .chant/trust.json lists for that key."
+            },
+            "run": {
+              "type": "object",
+              "required": [
+                "id",
+                "record"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "record": {
+                  "type": "object",
+                  "required": [
+                    "sha256"
+                  ],
+                  "properties": {
+                    "sha256": {
+                      "type": "string",
+                      "pattern": "^[0-9a-f]{64}$"
+                    }
+                  }
+                }
+              }
+            },
+            "unit": {
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "kind"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "kind": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  }
+                }
+              ]
+            },
+            "harness": {
+              "type": "object",
+              "required": [
+                "name",
+                "version"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "version": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            },
+            "model": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "provider": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "by": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      }
+    },
+    "statementVerdict": {
+      "type": "object",
+      "description": "One stored statement, judged against the runner keys at base and the run's record.",
+      "required": [
+        "status",
+        "reason"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "verified",
+            "mismatch",
+            "untrusted",
+            "invalid"
+          ],
+          "description": "verified: a listed runner key signed it and it matches the record. mismatch: a listed key signed it and it does not match. untrusted: no listed key signed it. invalid: not a DSSE envelope, not an agent-run statement, or naming another signer."
+        },
+        "code": {
+          "enum": [
+            "envelope-invalid",
+            "envelope-untrusted",
+            "run-statement-invalid",
+            "run-statement-signer-mismatch",
+            "run-statement-mismatch"
+          ],
+          "description": "Why it does not verify. Absent when verified."
+        },
+        "reason": {
+          "type": "string"
+        },
+        "signer": {
+          "type": "string"
+        },
+        "class": {
+          "enum": [
+            "runner",
+            "service"
+          ]
+        },
+        "keyid": {
+          "type": "string"
+        },
+        "statement": {
+          "$ref": "#/$defs/statement",
+          "description": "The statement, when verified."
+        }
+      }
+    },
+    "attestation": {
+      "type": "object",
+      "description": "The run's statements judged against the runner keys at base (#3192).",
+      "required": [
+        "status",
+        "signer",
+        "class",
+        "keyid",
+        "code",
+        "reason",
+        "commits",
+        "statements"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "signed",
+            "unsigned",
+            "mismatch",
+            "untrusted",
+            "invalid"
+          ],
+          "description": "signed: a stored statement verifies. unsigned: the ledger holds none. Otherwise the best failure, mismatch before untrusted before invalid."
+        },
+        "signer": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "class": {
+          "enum": [
+            "runner",
+            "service",
+            null
+          ]
+        },
+        "keyid": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "code": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "enum": [
+                "envelope-invalid",
+                "envelope-untrusted",
+                "run-statement-invalid",
+                "run-statement-signer-mismatch",
+                "run-statement-mismatch"
+              ]
+            }
+          ],
+          "description": "The code of the failure status reports, or null when signed or unsigned."
+        },
+        "reason": {
+          "type": "string"
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The commits the verified statement names. Empty unless signed."
+        },
+        "statements": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/statementVerdict"
+          },
+          "description": "One verdict per stored statement, in ledger order."
+        }
+      }
+    }
+  }
+}