request.proto

// Copyright 2021-2023 Zenauth Ltd.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

package cerbos.request.v1;

import "cerbos/engine/v1/engine.proto";
import "cerbos/policy/v1/policy.proto";
import "cerbos/schema/v1/schema.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "validate/validate.proto";

option csharp_namespace = "Cerbos.Api.V1.Request";
option go_package = "github.com/cerbos/cerbos/api/genpb/cerbos/request/v1;requestv1";
option java_package = "dev.cerbos.api.v1.request";

message PlanResourcesRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "PDP Resources Query Plan Request"}
  };

  string request_id = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Optional application-specific ID useful for correlating logs for analysis."
    example: "\"c2db17b8-4f9f-4fb1-acfd-9162a02be42b\""
  }];

  string action = 2 [
    (validate.rules).string.min_len = 1,
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Action to be applied to each resource in the list."
      example: "\"view:public\""
    }
  ];

  cerbos.engine.v1.Principal principal = 3 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];

  cerbos.engine.v1.PlanResourcesInput.Resource resource = 4 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];

  AuxData aux_data = 5 [(google.api.field_behavior) = OPTIONAL];

  bool include_meta = 6 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Opt to receive request processing metadata in the response."}];
}

// Deprecated. See CheckResourcesRequest.
message CheckResourceSetRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "PDP Request"}
  };

  string request_id = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Optional application-specific ID useful for correlating logs for analysis."
    example: "\"c2db17b8-4f9f-4fb1-acfd-9162a02be42b\""
  }];
  repeated string actions = 2 [
    (validate.rules).repeated = {
      unique: true,
      min_items: 1,
      items {
        string {min_len: 1}
      }
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of actions being performed on the set of resources."
      min_items: 1
      unique_items: true
      example: "[\"view:public\", \"comment\"]"
    }
  ];
  cerbos.engine.v1.Principal principal = 3 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];
  ResourceSet resource = 4 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];
  bool include_meta = 5 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Opt to receive request processing metadata in the response."}];
  AuxData aux_data = 6 [(google.api.field_behavior) = OPTIONAL];
}

message ResourceSet {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Set of resources to check"}
  };

  string kind = 1 [
    (validate.rules).string = {
      pattern: "^[[:alpha:]][[:word:]\\@\\.\\-/]*(\\:[[:alpha:]][[:word:]\\@\\.\\-/]*)*$",
      min_len: 1
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Resource kind."
      example: "\"album:object\""
      pattern: "^[[:alpha:]][[:word:]\\@\\.\\-]*(\\:[[:alpha:]][[:word:]\\@\\.\\-]*)*$"
    }
  ];
  string policy_version = 2 [
    (validate.rules).string.pattern = "^[[:word:]]*$",
    (google.api.field_behavior) = OPTIONAL,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "The policy version to use to evaluate this request. If not specified, will default to the server-configured default version.",
      pattern: "^[[:word:]]*$"
      example: "\"default\""
    }
  ];
  map<string, AttributesMap> instances = 3 [
    (validate.rules).map = {
      min_pairs: 1,
      no_sparse: true
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Set of resource instances to check. Each instance must be keyed by an application-specific unique identifier.",
      min_properties: 1
      example: "{\"XX125\":{\"attr\":{\"owner\":\"bugs_bunny\", \"public\": false, \"flagged\": false}}, \"XX225\":{\"attr\":{\"owner\":\"daffy_duck\", \"public\": true, \"flagged\": false}}}"
    }
  ];
  string scope = 4 [
    (validate.rules).string.pattern = "^([[:alnum:]][[:word:]\\-]*(\\.[[:word:]\\-]*)*)*$",
    (google.api.field_behavior) = OPTIONAL,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "A dot-separated scope that describes the hierarchy these resources belong to. This is used for determining policy inheritance."
      pattern: "^([[:alnum:]][[:word:]\\-]*(\\.[[:word:]\\-]*)*)*$"
    }
  ];
}

message AttributesMap {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Unique identifier for the resource instance."}
  };

  map<string, google.protobuf.Value> attr = 1 [
    (validate.rules).map.no_sparse = true,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Key-value pairs of contextual data about this instance that should be used during policy evaluation."}
  ];
}

// Deprecated. See CheckResourcesRequest.
message CheckResourceBatchRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "PDP Request"}
  };

  message BatchEntry {
    repeated string actions = 1 [
      (validate.rules).repeated = {
        unique: true,
        min_items: 1,
        items {
          string {min_len: 1}
        }
      },
      (google.api.field_behavior) = REQUIRED,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "List of actions being performed on the resource."
        min_items: 1
        unique_items: true
        example: "[\"view:public\", \"comment\"]"
      }
    ];
    cerbos.engine.v1.Resource resource = 2 [
      (validate.rules).message.required = true,
      (google.api.field_behavior) = REQUIRED
    ];
  }

  string request_id = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Optional application-specific ID useful for correlating logs for analysis."
    example: "\"c2db17b8-4f9f-4fb1-acfd-9162a02be42b\""
  }];
  cerbos.engine.v1.Principal principal = 2 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];
  repeated BatchEntry resources = 3 [
    (validate.rules).repeated = {min_items: 1},
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of resources and actions."
      min_items: 1
      unique_items: true
      example: "[{\"actions\":[\"view\",\"comment\"], \"resource\":{\"kind\":\"album:object\",\"policyVersion\":\"default\",\"id\":\"XX125\",\"attr\":{\"owner\":\"bugs_bunny\", \"public\": false, \"flagged\": false}}}]"
    }
  ];
  AuxData aux_data = 4;
}

// Structure of the request for the check resources API call.
message CheckResourcesRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Check resources request"}
  };

  message ResourceEntry {
    repeated string actions = 1 [
      (validate.rules).repeated = {
        unique: true,
        min_items: 1,
        items {
          string {min_len: 1}
        }
      },
      (google.api.field_behavior) = REQUIRED,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "List of actions being performed on the resource."
        min_items: 1
        unique_items: true
        example: "[\"view:public\", \"comment\"]"
      }
    ];
    cerbos.engine.v1.Resource resource = 2 [
      (validate.rules).message.required = true,
      (google.api.field_behavior) = REQUIRED
    ];
  }

  string request_id = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Optional application-specific ID useful for correlating logs for analysis."
    example: "\"c2db17b8-4f9f-4fb1-acfd-9162a02be42b\""
  }];
  bool include_meta = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Add request processing metadata to the response."}];
  cerbos.engine.v1.Principal principal = 3 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];
  repeated ResourceEntry resources = 4 [
    (validate.rules).repeated = {min_items: 1},
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of resources and actions."
      min_items: 1
      unique_items: true
      example: "[{\"actions\":[\"view\",\"comment\"], \"resource\":{\"kind\":\"album:object\",\"policyVersion\":\"default\",\"id\":\"XX125\",\"attr\":{\"owner\":\"bugs_bunny\", \"public\": false, \"flagged\": false}}}]"
    }
  ];
  AuxData aux_data = 5;
}

message AuxData {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Structured auxiliary data useful for evaluating the request"}
  };

  message JWT {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
      json_schema: {description: "JWT from the original request"}
    };

    string token = 1 [
      (validate.rules).string = {min_len: 1},
      (google.api.field_behavior) = REQUIRED,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "JWT from the original request"
        example: "\"eyJhbGciOiJFUzM4NCIsImtpZCI6IjE5TGZaYXRFZGc4M1lOYzVyMjNndU1KcXJuND0iLCJ0eXAiOiJKV1QifQ.eyJhdWQiOlsiY2VyYm9zLWp3dC10ZXN0cyJdLCJjdXN0b21BcnJheSI6WyJBIiwiQiIsIkMiXSwiY3VzdG9tSW50Ijo0MiwiY3VzdG9tTWFwIjp7IkEiOiJBQSIsIkIiOiJCQiIsIkMiOiJDQyJ9LCJjdXN0b21TdHJpbmciOiJmb29iYXIiLCJleHAiOjE5NDk5MzQwMzksImlzcyI6ImNlcmJvcy10ZXN0LXN1aXRlIn0.WN_tOScSpd_EI-P5EI1YlagxEgExSfBjAtcrgcF6lyWj1lGpR_GKx9goZEp2p_t5AVWXN_bjz_sMUmJdJa4cVd55Qm1miR-FKu6oNRHnSEWdMFmnArwPw-YDJWfylLFX\""
      }
    ];
    string key_set_id = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Key ID to use when decoding the token (defined in the Cerbos server configuration)"
      example: "\"my-keyset\""
    }];
  }

  JWT jwt = 1;
}

message File {
  string file_name = 1 [
    (validate.rules).string.min_len = 1,
    (google.api.field_behavior) = REQUIRED
  ];

  bytes contents = 2 [
    (validate.rules).bytes = {
      min_len: 1,
      max_len: 1048576
    },
    (google.api.field_behavior) = REQUIRED
  ];
}

message PlaygroundValidateRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Playground validate request"}
  };

  string playground_id = 1;

  repeated File files = 2 [
    (validate.rules).repeated = {
      min_items: 1,
      max_items: 30
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of files."
      min_items: 1
      max_items: 30
    }
  ];
}

message PlaygroundTestRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Playground test request"}
  };

  string playground_id = 1;

  repeated File files = 2 [
    (validate.rules).repeated = {
      min_items: 1,
      max_items: 30
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of files."
      min_items: 1
      max_items: 30
    }
  ];
}

message PlaygroundEvaluateRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Playground evaluate request"}
  };

  string playground_id = 1;

  repeated File files = 2 [
    (validate.rules).repeated = {
      min_items: 1,
      max_items: 30
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of files."
      min_items: 1
      max_items: 30
    }
  ];

  cerbos.engine.v1.Principal principal = 3 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];

  cerbos.engine.v1.Resource resource = 4 [
    (validate.rules).message.required = true,
    (google.api.field_behavior) = REQUIRED
  ];

  repeated string actions = 5 [
    (validate.rules).repeated = {
      unique: true,
      min_items: 1,
      max_items: 50,
      items {
        string {min_len: 1}
      }
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of actions being performed on the resource."
      min_items: 1
      max_items: 50
      unique_items: true
    }
  ];

  AuxData aux_data = 6;
}

message PlaygroundProxyRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Playground proxy request"}
  };

  string playground_id = 1;

  repeated File files = 2 [
    (validate.rules).repeated = {
      min_items: 1,
      max_items: 30
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of files."
      min_items: 1
      max_items: 30
    }
  ];

  oneof proxy_request {
    option (validate.required) = true;
    CheckResourceSetRequest check_resource_set = 3;
    CheckResourceBatchRequest check_resource_batch = 4;
    PlanResourcesRequest plan_resources = 5;
    CheckResourcesRequest check_resources = 6;
  }
}

message AddOrUpdatePolicyRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Add/update policy request"}
  };

  repeated cerbos.policy.v1.Policy policies = 1 [
    (validate.rules).repeated = {
      min_items: 1,
      max_items: 10
    },
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of policies."
      min_items: 1
      max_items: 10
    }
  ];
}

message ListAuditLogEntriesRequest {
  enum Kind {
    KIND_UNSPECIFIED = 0;
    KIND_ACCESS = 1;
    KIND_DECISION = 2;
  }

  message TimeRange {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
      json_schema: {description: "Entries between a time range."}
    };

    google.protobuf.Timestamp start = 1 [
      (validate.rules).timestamp = {
        required: true,
        lt_now: true,
      },
      (google.api.field_behavior) = REQUIRED,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Start date in ISO 8601 format."
        example: "\"2021-07-05T07:27:01+00:00\""
      }
    ];
    google.protobuf.Timestamp end = 2 [
      (validate.rules).timestamp = {
        required: true,
        lt_now: true,
      },
      (google.api.field_behavior) = REQUIRED,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "End date in ISO 8601 format."
        example: "\"2021-07-05T07:27:01+00:00\""
      }
    ];
  }

  Kind kind = 1 [
    (validate.rules).enum = {
      in: [
        1,
        2
      ]
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Kind of log entry"
      enum: [
        "KIND_ACCESS",
        "KIND_DECISION"
      ]
    }
  ];
  oneof filter {
    option (validate.required) = true;
    uint32 tail = 2 [
      (validate.rules).uint32.lte = 1000,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Last N entries."
        minimum: 1
        maximum: 1000
      }
    ];
    TimeRange between = 3;
    google.protobuf.Duration since = 4 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Entries since N hours/minutes ago"}];
    string lookup = 5 [
      (validate.rules).string = {pattern: "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"},
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "By Call ID"
        pattern: "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
      }
    ];
  }
}

message ServerInfoRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Server info request"}
  };
}

message ListPoliciesRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "List policies request"}
  };
  bool include_disabled = 1 [
    (google.api.field_behavior) = OPTIONAL,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Include disabled policies"}
  ];
}

message GetPolicyRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Get policy request"}
  };
  repeated string id = 1 [
    (google.api.field_behavior) = REQUIRED,
    (validate.rules).repeated = {
      unique: true,
      min_items: 1,
      max_items: 25,
      items {
        string {
          min_len: 1,
          max_len: 1280
        }
      }
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "For blob, disk, git stores use file name (<filename>.yaml). For mysql, postgres, sqlite3 use id (<kind>.<name>.<version>) of the policy"
      example: "\"principal.sarah.vdefault\""
    }
  ];
}

message DisablePolicyRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Disable policy request"}
  };
  repeated string id = 1 [
    (google.api.field_behavior) = REQUIRED,
    (validate.rules).repeated = {
      unique: true,
      min_items: 1,
      max_items: 25,
      items {
        string {
          min_len: 1,
          max_len: 1280
        }
      }
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Unique identifier for the policy"
      example: "\"principal.sarah.vdefault\""
    }
  ];
}

message AddOrUpdateSchemaRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Add/update schema request"}
  };

  repeated cerbos.schema.v1.Schema schemas = 1 [
    (google.api.field_behavior) = REQUIRED,
    (validate.rules).repeated = {
      min_items: 1,
      max_items: 10
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "List of schemas."
      min_items: 1
      max_items: 10
    }
  ];
}

message ListSchemasRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "List schema ids request"}
  };
}

message GetSchemaRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Get schema(s) request"}
  };
  repeated string id = 1 [
    (google.api.field_behavior) = REQUIRED,
    (validate.rules).repeated = {
      unique: true,
      min_items: 1,
      max_items: 25,
      items {
        string {
          min_len: 1,
          max_len: 255
        }
      }
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Unique identifier for the schema"
      example: "\"principal.json\""
    }
  ];
}

message DeleteSchemaRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Delete schema(s) request"}
  };
  repeated string id = 1 [
    (google.api.field_behavior) = REQUIRED,
    (validate.rules).repeated = {
      unique: true,
      min_items: 1,
      max_items: 25,
      items {
        string {
          min_len: 1,
          max_len: 255
        }
      }
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Unique identifier for the schema"
      example: "\"principal.json\""
    }
  ];
}

message ReloadStoreRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "Reload store request"}
  };

  bool wait = 1 [
    (google.api.field_behavior) = OPTIONAL,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Wait until the reloading process finalizes"}
  ];
}