validator/tracker.h

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

#ifndef THIRD_PARTY_CREDENTIO_VALIDATOR_TRACKER_H_
#define THIRD_PARTY_CREDENTIO_VALIDATOR_TRACKER_H_

#include <stdbool.h>

#include <string>

#include "absl/container/flat_hash_set.h"
#include "absl/strings/string_view.h"
#include "constants/status_codes.h"
#include "google/protobuf/repeated_ptr_field.h"
#include "proto/manifest.pb.h"
#include "proto/validation_status.pb.h"

namespace credentio {

// Tracks the validation process by accumulating the C2PA status codes returned
// in various validation steps.
class ValidationTracker {
 public:
  // Constructs a new validation tracker for the given manifest.
  // Status values will be recorded in the given manifest, and the URL of the
  // manifest itself will be used by default.
  explicit ValidationTracker(Manifest* manifest);

  // Constructs a new validation tracker for the given manifest label and
  // status set.
  explicit ValidationTracker(absl::string_view manifest_label,
                             ValidationStatusSet* status_set);

  // Returns a tracker that uses the URL of the given assertion by default.
  // Status values are recorded to the same location as the parent tracker.
  ValidationTracker AssertionTracker(absl::string_view assertion_label);

  struct RecordOptions {
    // The url to record with the status. If the url is empty, the manifest url
    // is used. If the url starts with "self#jumbf=", the supplied url is used.
    // Otherwise the supplied value is interpreted as a path relative to the
    // manifest url.
    absl::string_view url = "";
    // An optional explanation for the status.
    absl::string_view explanation = "";
  };

  // Records a C2PA success status code.
  void RecordSuccess(SuccessStatusCode status, RecordOptions options);

  // Records a C2PA informational status code.
  void RecordInformational(InformationalStatusCode status,
                           RecordOptions options);

  // Records a C2PA failure status code.
  void RecordFailure(FailureStatusCode status, RecordOptions options);

  // Returns if the validation process has any failures so far.
  bool HasFailures() const;
  // Returns the C2PA failure status codes observed so far.
  absl::flat_hash_set<std::string> GetFailures() const;
  // Returns the C2PA failure statuses observed so far.
  google::protobuf::RepeatedPtrField<ValidationStatus> GetFailureStatuses()
      const {
    return status_set_->failures();
  }
  // Returns the C2PA success status codes observed so far.
  absl::flat_hash_set<std::string> GetSuccesses() const;
  // Returns the C2PA success statuses observed so far.
  google::protobuf::RepeatedPtrField<ValidationStatus> GetSuccessStatuses()
      const {
    return status_set_->successes();
  }
  // Returns the C2PA informational status codes observed so far.
  absl::flat_hash_set<std::string> GetInformationals() const;
  // Returns the C2PA informational statuses observed so far.
  google::protobuf::RepeatedPtrField<ValidationStatus>
  GetInformationalStatuses() const {
    return status_set_->informationals();
  }

  // Merges the statuses from a ValidationStatusSet into this tracker.
  void MergeStatuses(const ValidationStatusSet& statuses);

 private:
  absl::string_view manifest_label_;
  absl::string_view assertion_label_;
  ValidationStatusSet* const status_set_;
  std::string id_;
};

}  // namespace credentio

#endif  // THIRD_PARTY_CREDENTIO_VALIDATOR_TRACKER_H_