jumbf/box.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.
//

// Types to represent deserialized JUMBF boxes, as defined by ISO/IEC 19566-5.
#ifndef THIRD_PARTY_CREDENTIO_JUMBF_BOX_H_
#define THIRD_PARTY_CREDENTIO_JUMBF_BOX_H_

#include <cstdint>
#include <optional>
#include <variant>
#include <vector>

#include "absl/strings/string_view.h"
#include "uuid/uuid.h"

namespace jumbf {

struct ContentBox;

struct UnknownBox {
  uint32_t type;
  absl::string_view payload;

  bool operator==(const UnknownBox&) const = default;
};

// See section A.3
struct DescriptionBox {
  // The type UUID, referred to simply as "type" in section A.3, not to be
  // confused with the 32 bit box type described in section 4.3 (all description
  // boxes must have box type "jumd").
  credentio::Uuid type_uuid;

  bool requestable = false;
  std::optional<absl::string_view> label;
  std::optional<uint32_t> id;
  // The SHA-256 hash of the associated content boxes. In identical byte order
  // to the serialized form as defined in the standard (FIPS PUB 180-4). This
  // value is taken directly from the serialized data and has not been validated
  // in any way.
  std::optional<absl::string_view> unvalidated_hash;
  std::vector<ContentBox> private_content;

  bool operator==(const DescriptionBox&) const = default;
};

// See section A.2, also see note on naming conventions in README.md
struct SuperBox {
  DescriptionBox description;
  std::vector<ContentBox> contents;
  absl::string_view raw_bytes;

  bool operator==(const SuperBox&) const = default;
};

// See section B.7
struct CborBox {
  absl::string_view payload;

  bool operator==(const CborBox&) const = default;
};

// See section B.6.2
struct EmbeddedFileDescriptionBox {
  absl::string_view media_type;
  bool external = false;
  std::optional<absl::string_view> file_name;

  bool operator==(const EmbeddedFileDescriptionBox&) const = default;
};

// See section B.6.3
struct BinaryDataBox {
  absl::string_view payload;

  bool operator==(const BinaryDataBox&) const = default;
};

// A super box that was not parsed because the recursion limit was reached.
struct SerializedSuperbox {
  // The entire serialized super box.
  absl::string_view serialized;

  bool operator==(const SerializedSuperbox&) const = default;
};

// See C2PA 2.0 section 8.3.1.3
struct C2paSaltBox {
  absl::string_view salt;

  bool operator==(const C2paSaltBox&) const = default;
};

struct JsonBox {
  absl::string_view payload;

  bool operator==(const JsonBox&) const = default;
};

struct UuidBox {
  absl::string_view payload;

  bool operator==(const UuidBox&) const = default;
};

struct ContentBox {
  absl::string_view raw_bytes;

  std::variant<UnknownBox, CborBox, SerializedSuperbox, SuperBox,
               EmbeddedFileDescriptionBox, BinaryDataBox, C2paSaltBox, JsonBox,
               UuidBox>
      payload;

  bool operator==(const ContentBox&) const = default;

  template <typename ExpectedBox>
  bool Holds() const {
    return std::holds_alternative<ExpectedBox>(payload);
  }

  // Retrieves the payload of type `DesiredBox`. Crashes if this content box
  // does not contain that type. Use `Holds<ExpectedBox>()` above to check the
  // contained type first to guarantee safety.
  template <typename DesiredBox>
  const DesiredBox& Get() const {
    return std::get<DesiredBox>(payload);
  }
};

}  // namespace jumbf

#endif  // THIRD_PARTY_CREDENTIO_JUMBF_BOX_H_