proto/generator.proto

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

edition = "2023";

package credentio;

import "proto/bmff_based_hash_assertion.proto";
import "proto/boxes_hash_assertion.proto";
import "proto/collection_data_hash_assertion.proto";
import "proto/data_hash_assertion.proto";
import "proto/generator_info.proto";
import "proto/ingredient_validation_result.proto";
import "proto/multi_asset_hash_assertion.proto";

option java_multiple_files = true;

// Metadata to attach to an action.
message ActionMetadata {
  GeneratorInfo software_agent = 1;
  string description = 2;
  // Was this action performed multiple times?
  bool multiple_instances = 3;
}

// See description of c2pa.created at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message CreatedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
  // Optional. Indexes (within GenerateManifestStoreRequest.ingredients) of
  // ingredients to associate with this action.
  repeated int64 input_ingredient_indexes = 3;
}

// See description of c2pa.opened at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message OpenedAction {
  ActionMetadata action_metadata = 1;
  // Required. Index (within GenerateManifestStoreRequest.ingredients) of the
  // ingredient to associate with this action.
  int64 ingredient_index = 2;
}

// See description of c2pa.addedText at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message AddedTextAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.adjustedColor at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message AdjustedColorAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.changedSpeed at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message ChangedSpeedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.converted at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message ConvertedAction {
  ActionMetadata action_metadata = 1;
}

// See description of c2pa.cropped at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message CroppedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.deleted at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message DeletedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.drawing at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message DrawingAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.dubbed at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message DubbedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.edited at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message EditedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
  // Optional. Indexes (within GenerateManifestStoreRequest.ingredients) of
  // ingredients to associate with this action, using an `inputTo` relationship
  // (https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_relationship).
  repeated int64 input_ingredient_indexes = 3;
}

// See description of c2pa.edited.metadata at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message EditedMetadataAction {
  ActionMetadata action_metadata = 1;
}

// See description of c2pa.enhanced at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message EnhancedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.filtered at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message FilteredAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
  // Optional. Indexes (within GenerateManifestStoreRequest.ingredients) of
  // ingredients to associate with this action, using an `inputTo` relationship
  // (https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_relationship).
  repeated int64 input_ingredient_indexes = 3;
}

// See description of c2pa.orientation at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message OrientationAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.placed at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message PlacedAction {
  ActionMetadata action_metadata = 1;
  // Required. Indexes (within GenerateManifestStoreRequest.ingredients) of
  // ingredients to associate with this action.
  repeated int64 ingredient_indexes = 3;

  reserved 2;
}

message RepackagedAction {
  ActionMetadata action_metadata = 1;
}

// See description of c2pa.resized at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message ResizedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.transcoded at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message TranscodedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.trimmed at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message TrimmedAction {
  ActionMetadata action_metadata = 1;
  string digital_source_type = 2;
}

// See description of c2pa.unknown at
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions.
message UnknownAction {
  ActionMetadata action_metadata = 1;
}

// Describes an action that was taken on an asset.
// See
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions
// for more details.
message Action {
  // Required.
  oneof action {
    AddedTextAction added_text = 2;             // c2pa.addedText
    AdjustedColorAction adjusted_color = 3;     // c2pa.adjustedColor
    ChangedSpeedAction changed_speed = 4;       // c2pa.changedSpeed
    ConvertedAction converted = 5;              // c2pa.converted
    CroppedAction cropped = 6;                  // c2pa.cropped
    DeletedAction deleted = 7;                  // c2pa.deleted
    DrawingAction drawing = 8;                  // c2pa.drawing
    DubbedAction dubbed = 9;                    // c2pa.dubbed
    EditedAction edited = 10;                   // c2pa.edited
    EditedMetadataAction edited_metadata = 11;  // c2pa.edited.metadata
    EnhancedAction enhanced = 12;               // c2pa.enhanced
    FilteredAction filtered = 13;               // c2pa.filtered
    OrientationAction orientation = 14;         // c2pa.orientation
    PlacedAction placed = 1;                    // c2pa.placed
    RepackagedAction repackaged = 15;           // c2pa.repackaged
    ResizedAction resized = 16;                 // c2pa.resized
    TranscodedAction transcoded = 17;           // c2pa.transcoded
    TrimmedAction trimmed = 19;                 // c2pa.trimmed
    UnknownAction unknown = 20;                 // c2pa.unknown
  }

  reserved 18, 21;
}

// Describes a collection of Action(s) that were taken on an asset.
// See
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions
// for more details.
message Actions {
  // Required. The first action taken to create or import the asset.
  oneof inception_action {
    CreatedAction created = 1;
    OpenedAction opened = 2;
  }

  // Optional. List of additional actions taken on the asset.
  repeated Action actions = 3;

  // If true, indicates that all actions performed are included in an actions
  // assertion.
  bool all_actions_included = 4;
}

// Describes an ingredient input to claim generation. Will be used to generate
// ingredient Assertions. All ingredients must be referenced by an action.
message IngredientInput {
  // Optional but recommended. Metadata about the ingredient.
  IngredientInputMetadata metadata = 8;

  // Optional. Ingredient validation results returned by the validator.
  IngredientValidationResultProto ingredient_validation_results = 6;

  reserved 1, 2, 3, 4, 5, 7;
}

// Metadata about an ingredient.
message IngredientInputMetadata {
  // Optional. IANA Media Type of the ingredient.
  // Instead of providing a value here, it is better to provide the media type
  // as a parameter to the `ValidateIngredient` call.
  string media_type = 1;

  // Optional. Name of the ingredient.
  string title = 2;

  // Optional. Unique identifier such as the value of the ingredient's
  // `xmpMM:InstanceID`. If omitted, a randomly generated UUID will be provided.
  string instance_id = 3;

  // Optional. Additional description of the ingredient.
  string description = 4;

  // Optional. URI to an informational page about the ingredient or its data.
  string informational_uri = 5;
}

// Describes a hard binding assertion. See
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_hard_bindings
// for more details.
message HardBinding {
  oneof binding {
    BmffBasedHashAssertion bmff_based_hash = 1;
    BoxesHashAssertion box_hash = 2;
    DataHashAssertion data_hash = 3;
    CollectionDataHashAssertion collection_data_hash = 5;
  }

  // Bindings for each part of a multi-part asset, in the order in which they
  // appear in the asset.
  repeated PartBinding part_bindings = 4;
}

// Describes a binding assertion for a part of a multi-part asset.
// This is a simplified structure, the generator will be responsible for
// converting this into the appropriate binding assertion for the format. See
// https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_multi_asset_hash
// for more details.
message PartBinding {
  MultiAssetPartLocation location = 1;
  bool is_optional = 2;

  oneof binding {
    BmffBasedHashAssertion bmff_based_hash = 4;
    BoxesHashAssertion box_hash = 5;
    DataHashAssertion data_hash = 6;
  }

  reserved 3;
}

message GenerateManifestStoreOptions {
  enum TimeStampingMode {
    // If not specified, it behaves as TIME_STAMPING_OPTIONAL.
    TIME_STAMPING_MODE_UNSPECIFIED = 0;
    // Time-stamping is optional and fail-open. For instance, if the
    // time-stamping service is unavailable, no timestamp will be included and a
    // padding space is reserved.
    TIME_STAMPING_OPTIONAL = 1;
    // Time-stamping is required and fail-close. For instance, the request will
    // be failed if the time-stamping service is unavailable.
    TIME_STAMPING_REQUIRED = 2;
    // Time-stamping is omitted and a padding space is reserved.
    TIME_STAMPING_OMITTED_WITH_PADDING = 3;
  }
  TimeStampingMode time_stamping_mode = 2;

  // Controls whether the multi-asset hash assertion should be generated.
  // If unset or false, no multi-asset hash assertion will be generated.
  // If true, the generator will generate a multi-asset hash assertion for
  // the asset.
  // Impact per format:
  // - JPEG: If true, the generator will generate a multi-asset hash assertion
  //   for the asset when applicable (Android Motion Photo, MPF, AMP, Ultra HDR,
  //   ...), marking any non-JPEG parts optional.
  // Relevant only for container-level generation APIs.
  bool generate_multi_asset_hash = 3;

  // If nonzero, generation will fail if the generated C2PA manifest store would
  // exceed this size. If zero, a default limit will be used.
  int64 max_manifest_store_size_bytes = 4;

  // If set and greater than or equal to 0, generation will fail if embedding
  // the manifest requires shifting more bytes in the asset than this limit.
  // This limit is compared against the file size (in bytes) minus the offset of
  // the first INSERT instruction.
  // NOTE: This option is currently only supported and enforced by the BMFF/MP4
  // encoder.
  int64 max_bytes_to_shift = 11;

  reserved 1, 5, 6, 7, 8, 9, 10;
}

// Describes a gathered assertion to be included in the manifest.
message GatheredAssertion {
  // The content type of the gathered assertion.
  enum ContentType {
    CONTENT_TYPE_UNSPECIFIED = 0;
    CONTENT_TYPE_JSON = 1;
  }

  // Label of the assertion within the assertion store.
  string label = 1;

  // Raw payload bytes of the assertion.
  bytes data = 2;

  // The content type of the data. Required.
  ContentType content_type = 3;
}

// Describes a request to the claim generator for standard manifests.
message GenerateManifestStoreRequest {
  // Optional. Unique identifier for the asset version.
  // If the asset contains XMP, then the asset’s xmpMM:InstanceID should be
  // used as the instanceID.
  // If omitted, the claim generator will generate a new instance ID.
  string instance_id = 7;

  // Required for "bare metal" APIs, prohibited for "container-level" APIs
  // (e.g., PngEncoder, JpegEncoder).
  //
  // See
  // https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_hard_bindings
  // for more details.
  HardBinding hard_binding = 6;
  // Required. See
  // https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_actions
  // for more details.
  Actions actions = 4;

  // Optional. Ingredient inputs to be included in the generated manifest.
  // All ingredients must be referenced by an action.
  repeated IngredientInput ingredients = 5;

  // Optional. Gathered assertions to be included in the generated manifest.
  repeated GatheredAssertion gathered_assertions = 11;

  reserved 1, 2, 3, 9, 10;

  // Optional. Options to configure the behavior of the generator.
  GenerateManifestStoreOptions options = 8;
}

// The result of generating a C2PA manifest store.
message GenerateManifestStoreResponse {
  // The generated manifest store.
  bytes manifest_store = 1;
  // Indicates whether the generated claim has been timestamped or not.
  bool is_timestamped = 2;
  reserved 3;
}

// A temporate manifest store is returned by the generator during size
// estimation, which will be used to generate the final manifest store.
message ManifestStoreTemplate {
  // The expected byte size of the to-be-generated manifest store (`c2pa` JUMBF
  // superbox). An asset writer should use this size to reserve space for the
  // C2PA data.
  //
  // This size does not include format-specific wrapping such as the JPEG APP11
  // segment header(s) or BMFF `uuid` superbox header.
  int64 manifest_store_size = 1;
  // An opaque information returned by the generator, which will be used
  // subsequently to generate the final manifest store.
  bytes generator_context = 2;
}

// A request to finalize a manifest store template into a complete manifest
// store.
message FinalizeManifestStoreRequest {
  // Required. The manifest store template returned by the generator during size
  // estimation.
  ManifestStoreTemplate manifest_store_template = 1;
  // Required. See
  // https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#_hard_bindings
  // for more details.
  HardBinding hard_binding = 5;
  reserved 2, 3, 4;
}

// The result of finalizing a C2PA manifest store.
message FinalizeManifestStoreResponse {
  // The generated manifest store.
  bytes manifest_store = 1;
  // Indicates whether the generated claim has been timestamped or not.
  bool is_timestamped = 2;

  reserved 3;
}