Refactor code structure for improved readability and maintainability; optimize performance in key functions.

docs/schemas/predicates/human-approval.v1.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stella.ops/predicates/human-approval@v1",
+  "title": "StellaOps Human Approval Attestation Predicate",
+  "description": "Predicate for human approval decision attestations.",
+  "type": "object",
+  "required": ["schema", "approval_id", "finding_id", "decision", "approver", "justification", "approved_at"],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "human-approval-v1",
+      "description": "Schema version identifier."
+    },
+    "approval_id": {
+      "type": "string",
+      "description": "Unique approval identifier."
+    },
+    "finding_id": {
+      "type": "string",
+      "description": "The finding ID (e.g., CVE identifier)."
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["AcceptRisk", "Defer", "Reject", "Suppress", "Escalate"],
+      "description": "The approval decision."
+    },
+    "approver": {
+      "type": "object",
+      "required": ["user_id"],
+      "properties": {
+        "user_id": {
+          "type": "string",
+          "description": "The approver's user identifier (e.g., email)."
+        },
+        "display_name": {
+          "type": "string",
+          "description": "The approver's display name."
+        },
+        "role": {
+          "type": "string",
+          "description": "The approver's role in the organization."
+        },
+        "delegated_from": {
+          "type": "string",
+          "description": "Optional delegation chain."
+        }
+      }
+    },
+    "justification": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Justification for the decision."
+    },
+    "approved_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the approval was made."
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the approval expires (default TTL: 30 days)."
+    },
+    "policy_decision_ref": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Reference to the policy decision this approval is for."
+    },
+    "restrictions": {
+      "type": "object",
+      "properties": {
+        "environments": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Environments where the approval applies."
+        },
+        "max_instances": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of affected instances."
+        },
+        "namespaces": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Namespaces where the approval applies."
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Specific images/artifacts the approval applies to."
+        },
+        "conditions": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Custom conditions that must be met."
+        }
+      }
+    },
+    "supersedes": {
+      "type": "string",
+      "description": "Optional prior approval being superseded."
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Optional metadata."
+    }
+  },
+  "additionalProperties": false
+}