{
  "$id": "https://stella.ops/schema/attestor-transport.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AttestorTransport",
  "description": "Attestor SDK transport contract for in-toto/DSSE attestation creation, verification, and storage",
  "type": "object",
  "oneOf": [
    { "$ref": "#/$defs/AttestationRequest" },
    { "$ref": "#/$defs/AttestationResponse" },
    { "$ref": "#/$defs/VerificationRequest" },
    { "$ref": "#/$defs/VerificationResponse" }
  ],
  "$defs": {
    "AttestationRequest": {
      "type": "object",
      "required": ["requestType", "requestId", "predicateType", "subject", "predicate"],
      "properties": {
        "requestType": {
          "type": "string",
          "const": "CREATE_ATTESTATION"
        },
        "requestId": {
          "type": "string",
          "format": "uuid",
          "description": "Unique request identifier for idempotency"
        },
        "correlationId": {
          "type": "string",
          "description": "Correlation ID for tracing"
        },
        "predicateType": {
          "type": "string",
          "format": "uri",
          "description": "in-toto predicate type URI",
          "examples": [
            "https://slsa.dev/provenance/v1",
            "https://stella.ops/attestation/vex-export/v1",
            "https://stella.ops/attestation/vuln-scan/v1"
          ]
        },
        "subject": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AttestationSubject"
          },
          "minItems": 1,
          "description": "Subjects being attested"
        },
        "predicate": {
          "type": "object",
          "additionalProperties": true,
          "description": "Predicate payload (schema depends on predicateType)"
        },
        "signingOptions": {
          "$ref": "#/$defs/SigningOptions"
        }
      }
    },
    "AttestationResponse": {
      "type": "object",
      "required": ["responseType", "requestId", "status"],
      "properties": {
        "responseType": {
          "type": "string",
          "const": "ATTESTATION_CREATED"
        },
        "requestId": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "type": "string",
          "enum": ["SUCCESS", "FAILED", "PENDING"]
        },
        "attestation": {
          "$ref": "#/$defs/AttestationEnvelope",
          "description": "Created attestation envelope (if SUCCESS)"
        },
        "error": {
          "$ref": "#/$defs/AttestationError",
          "description": "Error details (if FAILED)"
        }
      }
    },
    "VerificationRequest": {
      "type": "object",
      "required": ["requestType", "requestId", "envelope"],
      "properties": {
        "requestType": {
          "type": "string",
          "const": "VERIFY_ATTESTATION"
        },
        "requestId": {
          "type": "string",
          "format": "uuid"
        },
        "envelope": {
          "type": "string",
          "description": "Base64-encoded DSSE envelope"
        },
        "verificationOptions": {
          "$ref": "#/$defs/VerificationOptions"
        }
      }
    },
    "VerificationResponse": {
      "type": "object",
      "required": ["responseType", "requestId", "verified"],
      "properties": {
        "responseType": {
          "type": "string",
          "const": "ATTESTATION_VERIFIED"
        },
        "requestId": {
          "type": "string",
          "format": "uuid"
        },
        "verified": {
          "type": "boolean",
          "description": "Whether verification succeeded"
        },
        "verificationResult": {
          "$ref": "#/$defs/VerificationResult"
        },
        "error": {
          "$ref": "#/$defs/AttestationError"
        }
      }
    },
    "AttestationSubject": {
      "type": "object",
      "required": ["name", "digest"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Subject URI or name"
        },
        "digest": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Algorithm to digest mapping"
        }
      }
    },
    "SigningOptions": {
      "type": "object",
      "properties": {
        "keyId": {
          "type": "string",
          "description": "Key identifier to use for signing"
        },
        "provider": {
          "type": "string",
          "description": "Crypto provider name",
          "examples": ["default", "pkcs11", "kms", "gost"]
        },
        "algorithm": {
          "type": "string",
          "description": "Signing algorithm",
          "examples": ["ES256", "RS256", "EdDSA", "GOST_R34_11_2012_256"]
        },
        "transparencyLog": {
          "type": "boolean",
          "default": false,
          "description": "Whether to submit to Rekor transparency log"
        },
        "timestampAuthority": {
          "type": "string",
          "format": "uri",
          "description": "RFC 3161 timestamp authority URL"
        }
      }
    },
    "VerificationOptions": {
      "type": "object",
      "properties": {
        "trustedKeyIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Trusted key identifiers"
        },
        "trustedIssuers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Trusted issuer identities"
        },
        "requireTransparencyLog": {
          "type": "boolean",
          "default": false,
          "description": "Require valid transparency log entry"
        },
        "requireTimestamp": {
          "type": "boolean",
          "default": false,
          "description": "Require trusted timestamp"
        }
      }
    },
    "AttestationEnvelope": {
      "type": "object",
      "required": ["payloadType", "payload", "signatures"],
      "properties": {
        "payloadType": {
          "type": "string",
          "const": "application/vnd.in-toto+json",
          "description": "DSSE payload type"
        },
        "payload": {
          "type": "string",
          "description": "Base64-encoded in-toto statement"
        },
        "signatures": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DsseSignature"
          },
          "minItems": 1
        },
        "envelopeDigest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$",
          "description": "Digest of the envelope"
        },
        "transparencyLogEntry": {
          "$ref": "#/$defs/TransparencyLogEntry"
        }
      }
    },
    "DsseSignature": {
      "type": "object",
      "required": ["keyid", "sig"],
      "properties": {
        "keyid": {
          "type": "string",
          "description": "Key identifier"
        },
        "sig": {
          "type": "string",
          "description": "Base64-encoded signature"
        }
      }
    },
    "TransparencyLogEntry": {
      "type": "object",
      "properties": {
        "logIndex": {
          "type": "integer",
          "description": "Entry index in the log"
        },
        "logId": {
          "type": "string",
          "description": "Log identifier"
        },
        "integratedTime": {
          "type": "string",
          "format": "date-time",
          "description": "When entry was integrated"
        },
        "inclusionProof": {
          "type": "string",
          "description": "Base64-encoded inclusion proof"
        },
        "entryUri": {
          "type": "string",
          "format": "uri",
          "description": "URI to the log entry"
        }
      }
    },
    "VerificationResult": {
      "type": "object",
      "properties": {
        "signatureValid": {
          "type": "boolean"
        },
        "predicateType": {
          "type": "string"
        },
        "subjects": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AttestationSubject"
          }
        },
        "signerIdentity": {
          "type": "string",
          "description": "Verified signer identity"
        },
        "signedAt": {
          "type": "string",
          "format": "date-time"
        },
        "transparencyLogVerified": {
          "type": "boolean"
        },
        "timestampVerified": {
          "type": "boolean"
        }
      }
    },
    "AttestationError": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code",
          "examples": [
            "KEY_NOT_FOUND",
            "SIGNATURE_INVALID",
            "PREDICATE_VALIDATION_FAILED",
            "TRANSPARENCY_LOG_UNAVAILABLE"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message"
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional error details"
        }
      }
    }
  },
  "examples": [
    {
      "requestType": "CREATE_ATTESTATION",
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "correlationId": "scan-job-12345",
      "predicateType": "https://stella.ops/attestation/vuln-scan/v1",
      "subject": [
        {
          "name": "registry.example.com/app:v1.2.3",
          "digest": {
            "sha256": "7d9cd5f1a2a0dd9a41a2c43a5b7d8a0bcd9e34cf39b3f43a70595c834f0a4aee"
          }
        }
      ],
      "predicate": {
        "scanId": "scan-12345",
        "scanner": "stellaops-scanner/1.0.0",
        "completedAt": "2025-11-21T10:00:00Z",
        "vulnerabilities": {
          "critical": 2,
          "high": 5,
          "medium": 12,
          "low": 8
        }
      },
      "signingOptions": {
        "keyId": "scanner-signing-key-001",
        "algorithm": "ES256",
        "transparencyLog": true
      }
    }
  ]
}