{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://stella-ops.org/schemas/attestation-pointer.schema.json",
  "title": "StellaOps Attestation Pointer Schema",
  "description": "Schema for attestation pointers linking findings to verification reports and attestation envelopes. Unblocks LEDGER-ATTEST-73-001 and 73-002.",
  "type": "object",
  "definitions": {
    "AttestationPointer": {
      "type": "object",
      "description": "Pointer from a finding to its related attestation artifacts",
      "required": ["pointer_id", "finding_id", "attestation_type", "created_at"],
      "properties": {
        "pointer_id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier for this pointer"
        },
        "finding_id": {
          "type": "string",
          "format": "uuid",
          "description": "Finding this pointer references"
        },
        "attestation_type": {
          "type": "string",
          "enum": [
            "verification_report",
            "dsse_envelope",
            "slsa_provenance",
            "vex_attestation",
            "sbom_attestation",
            "scan_attestation",
            "policy_attestation",
            "approval_attestation"
          ],
          "description": "Type of attestation being pointed to"
        },
        "attestation_ref": {
          "$ref": "#/definitions/AttestationRef"
        },
        "relationship": {
          "type": "string",
          "enum": ["verified_by", "attested_by", "signed_by", "approved_by", "derived_from"],
          "description": "Semantic relationship to the attestation"
        },
        "verification_result": {
          "$ref": "#/definitions/VerificationResult"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "created_by": {
          "type": "string",
          "description": "Service or user that created the pointer"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "AttestationRef": {
      "type": "object",
      "description": "Reference to an attestation artifact",
      "required": ["digest"],
      "properties": {
        "attestation_id": {
          "type": "string",
          "format": "uuid"
        },
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Content-addressable digest of the attestation"
        },
        "storage_uri": {
          "type": "string",
          "format": "uri",
          "description": "URI to retrieve the attestation"
        },
        "payload_type": {
          "type": "string",
          "description": "DSSE payload type (e.g., application/vnd.in-toto+json)"
        },
        "predicate_type": {
          "type": "string",
          "description": "in-toto predicate type URI"
        },
        "subject_digests": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$"
          },
          "description": "Digests of subjects this attestation covers"
        },
        "signer_info": {
          "$ref": "#/definitions/SignerInfo"
        },
        "rekor_entry": {
          "$ref": "#/definitions/RekorEntryRef"
        }
      }
    },
    "SignerInfo": {
      "type": "object",
      "description": "Information about the attestation signer",
      "properties": {
        "key_id": {
          "type": "string",
          "description": "Key identifier"
        },
        "issuer": {
          "type": "string",
          "description": "Certificate issuer (for Fulcio keyless signing)"
        },
        "subject": {
          "type": "string",
          "description": "Certificate subject (email, OIDC identity)"
        },
        "certificate_chain": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "PEM-encoded certificate chain"
        },
        "signed_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "RekorEntryRef": {
      "type": "object",
      "description": "Reference to Rekor transparency log entry",
      "properties": {
        "log_index": {
          "type": "integer",
          "minimum": 0
        },
        "log_id": {
          "type": "string"
        },
        "uuid": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "integrated_time": {
          "type": "integer",
          "description": "Unix timestamp of log entry"
        }
      }
    },
    "VerificationResult": {
      "type": "object",
      "description": "Result of attestation verification",
      "required": ["verified", "verified_at"],
      "properties": {
        "verified": {
          "type": "boolean",
          "description": "Whether verification passed"
        },
        "verified_at": {
          "type": "string",
          "format": "date-time"
        },
        "verifier": {
          "type": "string",
          "description": "Service that performed verification"
        },
        "verifier_version": {
          "type": "string"
        },
        "policy_ref": {
          "type": "string",
          "description": "Reference to verification policy used"
        },
        "checks": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/VerificationCheck"
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "VerificationCheck": {
      "type": "object",
      "description": "Individual verification check result",
      "required": ["check_type", "passed"],
      "properties": {
        "check_type": {
          "type": "string",
          "enum": [
            "signature_valid",
            "certificate_valid",
            "certificate_not_expired",
            "certificate_not_revoked",
            "rekor_entry_valid",
            "timestamp_valid",
            "policy_met",
            "identity_verified",
            "issuer_trusted"
          ]
        },
        "passed": {
          "type": "boolean"
        },
        "details": {
          "type": "string"
        },
        "evidence": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "VerificationReport": {
      "type": "object",
      "description": "Full verification report for a finding",
      "required": ["report_id", "finding_id", "created_at", "overall_result"],
      "properties": {
        "report_id": {
          "type": "string",
          "format": "uuid"
        },
        "finding_id": {
          "type": "string",
          "format": "uuid"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "overall_result": {
          "type": "string",
          "enum": ["passed", "failed", "partial", "not_applicable"]
        },
        "attestation_results": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AttestationVerificationResult"
          }
        },
        "policy_evaluations": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PolicyEvaluationResult"
          }
        },
        "summary": {
          "type": "string"
        },
        "recommendations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "AttestationVerificationResult": {
      "type": "object",
      "description": "Verification result for a specific attestation",
      "required": ["attestation_ref", "verification_result"],
      "properties": {
        "attestation_ref": {
          "$ref": "#/definitions/AttestationRef"
        },
        "verification_result": {
          "$ref": "#/definitions/VerificationResult"
        },
        "relevance": {
          "type": "string",
          "enum": ["primary", "supporting", "contextual"],
          "description": "How relevant this attestation is to the finding"
        }
      }
    },
    "PolicyEvaluationResult": {
      "type": "object",
      "description": "Result of policy evaluation against attestations",
      "required": ["policy_id", "result"],
      "properties": {
        "policy_id": {
          "type": "string"
        },
        "policy_name": {
          "type": "string"
        },
        "policy_version": {
          "type": "string"
        },
        "result": {
          "type": "string",
          "enum": ["passed", "failed", "skipped", "error"]
        },
        "reason": {
          "type": "string"
        },
        "attestations_evaluated": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Attestation IDs evaluated by this policy"
        }
      }
    },
    "DsseEnvelope": {
      "type": "object",
      "description": "DSSE envelope containing attestation",
      "required": ["payloadType", "payload", "signatures"],
      "properties": {
        "payloadType": {
          "type": "string",
          "description": "MIME type of payload"
        },
        "payload": {
          "type": "string",
          "contentEncoding": "base64",
          "description": "Base64-encoded payload"
        },
        "signatures": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/DsseSignature"
          },
          "minItems": 1
        }
      }
    },
    "DsseSignature": {
      "type": "object",
      "description": "Signature on DSSE envelope",
      "required": ["sig"],
      "properties": {
        "keyid": {
          "type": "string"
        },
        "sig": {
          "type": "string",
          "contentEncoding": "base64"
        },
        "cert": {
          "type": "string",
          "contentEncoding": "base64",
          "description": "Fulcio certificate for keyless signing"
        }
      }
    },
    "AttestationSearchQuery": {
      "type": "object",
      "description": "Query for searching attestations by finding criteria",
      "properties": {
        "finding_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "attestation_types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "verification_status": {
          "type": "string",
          "enum": ["verified", "unverified", "failed", "any"]
        },
        "created_after": {
          "type": "string",
          "format": "date-time"
        },
        "created_before": {
          "type": "string",
          "format": "date-time"
        },
        "signer_identity": {
          "type": "string",
          "description": "Filter by signer email or identity"
        },
        "predicate_type": {
          "type": "string",
          "description": "Filter by in-toto predicate type"
        }
      }
    },
    "AttestationSearchResult": {
      "type": "object",
      "description": "Result of attestation search",
      "required": ["pointers", "total_count"],
      "properties": {
        "pointers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AttestationPointer"
          }
        },
        "total_count": {
          "type": "integer",
          "minimum": 0
        },
        "next_page_token": {
          "type": "string"
        }
      }
    },
    "FindingAttestationSummary": {
      "type": "object",
      "description": "Summary of attestations for a finding",
      "required": ["finding_id", "attestation_count"],
      "properties": {
        "finding_id": {
          "type": "string",
          "format": "uuid"
        },
        "attestation_count": {
          "type": "integer",
          "minimum": 0
        },
        "verified_count": {
          "type": "integer",
          "minimum": 0
        },
        "latest_attestation": {
          "type": "string",
          "format": "date-time"
        },
        "attestation_types": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "overall_verification_status": {
          "type": "string",
          "enum": ["all_verified", "partially_verified", "none_verified", "no_attestations"]
        }
      }
    }
  },
  "properties": {
    "pointers": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/AttestationPointer"
      }
    }
  },
  "examples": [
    {
      "pointers": [
        {
          "pointer_id": "550e8400-e29b-41d4-a716-446655440000",
          "finding_id": "660e8400-e29b-41d4-a716-446655440001",
          "attestation_type": "dsse_envelope",
          "attestation_ref": {
            "attestation_id": "770e8400-e29b-41d4-a716-446655440002",
            "digest": "sha256:abc123def456789012345678901234567890123456789012345678901234abcd",
            "storage_uri": "s3://attestations/770e8400.../attestation.json",
            "payload_type": "application/vnd.in-toto+json",
            "predicate_type": "https://slsa.dev/provenance/v1",
            "subject_digests": [
              "sha256:def456..."
            ],
            "signer_info": {
              "key_id": "fulcio:abc123",
              "issuer": "https://accounts.google.com",
              "subject": "scanner@stellaops.iam.gserviceaccount.com",
              "signed_at": "2025-12-06T10:00:00Z"
            },
            "rekor_entry": {
              "log_index": 12345678,
              "log_id": "c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d",
              "uuid": "24296fb24b8ad77a12345678901234567890123456789012345678901234abcd",
              "integrated_time": 1733479200
            }
          },
          "relationship": "verified_by",
          "verification_result": {
            "verified": true,
            "verified_at": "2025-12-06T10:05:00Z",
            "verifier": "stellaops-attestor",
            "verifier_version": "2025.10.0",
            "checks": [
              {
                "check_type": "signature_valid",
                "passed": true,
                "details": "ECDSA signature verified"
              },
              {
                "check_type": "certificate_valid",
                "passed": true,
                "details": "Fulcio certificate chain verified"
              },
              {
                "check_type": "rekor_entry_valid",
                "passed": true,
                "details": "Rekor inclusion proof verified"
              }
            ],
            "warnings": [],
            "errors": []
          },
          "created_at": "2025-12-06T10:05:00Z",
          "created_by": "attestor-service"
        }
      ]
    }
  ]
}