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

syntax = "proto3";

package cerbos.engine.v1;

import "buf/validate/validate.proto";
import "cerbos/effect/v1/effect.proto";
import "cerbos/schema/v1/schema.proto";
import "google/api/expr/v1alpha1/checked.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/struct.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

option csharp_namespace = "Cerbos.Api.V1.Engine";
option go_package = "github.com/cerbos/cerbos/api/genpb/cerbos/engine/v1;enginev1";
option java_package = "dev.cerbos.api.v1.engine";

message PlanResourcesInput {
  message Resource {
    string kind = 1 [
      (buf.validate.field).string = {min_len: 1},
      (buf.validate.field).required = true,
      (google.api.field_behavior) = REQUIRED,
      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
        description: "Resource kind."
        example: "\"album:object\""
      }
    ];

    map<string, google.protobuf.Value> attr = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Key-value pairs of contextual data about the resource that are known at a time of the request."}];

    string policy_version = 3 [
      (buf.validate.field).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\""
      }
    ];

    string scope = 4 [
      (buf.validate.field).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 this resource belongs to. This is used for determining policy inheritance."
        pattern: "^([[:alnum:]][[:word:]\\-]*(\\.[[:word:]\\-]*)*)*$"
      }
    ];
  }

  string request_id = 1;
  string action = 2;
  Principal principal = 3;
  Resource resource = 4;
  AuxData aux_data = 5;
  bool include_meta = 6;
}

message PlanResourcesAst {
  message Node {
    oneof node {
      LogicalOperation logical_operation = 1;
      google.api.expr.v1alpha1.CheckedExpr expression = 2;
    }
  }

  message LogicalOperation {
    enum Operator {
      OPERATOR_UNSPECIFIED = 0;
      OPERATOR_AND = 1;
      OPERATOR_OR = 2;
      OPERATOR_NOT = 3;
    }
    Operator operator = 1;
    repeated Node nodes = 2;
  }

  Node filter_ast = 1;
}

message PlanResourcesFilter {
  message Expression {
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
      json_schema: {description: "CEL expression"}
    };

    string operator = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Operator"}];

    message Operand {
      oneof node {
        google.protobuf.Value value = 1;
        Expression expression = 2;
        string variable = 3;
      }
    }

    repeated Operand operands = 2;
  }

  enum Kind {
    KIND_UNSPECIFIED = 0;
    KIND_ALWAYS_ALLOWED = 1;
    KIND_ALWAYS_DENIED = 2;
    KIND_CONDITIONAL = 3;
  }

  Kind kind = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Filter kind. Defines whether the given action is always allowed, always denied or allowed conditionally."}];

  Expression.Operand condition = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {description: "Filter condition. Only populated if kind is KIND_CONDITIONAL."}];
}

message PlanResourcesOutput {
  string request_id = 1;
  string action = 2;
  string kind = 3;
  string policy_version = 4;
  string scope = 5;
  PlanResourcesFilter filter = 6;
  string filter_debug = 7;
  repeated cerbos.schema.v1.ValidationError validation_errors = 8;
}

message CheckInput {
  string request_id = 1;
  Resource resource = 2 [
    (buf.validate.field).required = true,
    (google.api.field_behavior) = REQUIRED
  ];
  Principal principal = 3 [
    (buf.validate.field).required = true,
    (google.api.field_behavior) = REQUIRED
  ];
  repeated string actions = 4 [
    (buf.validate.field).repeated = {
      unique: true
      items: {
        string: {min_len: 1}
      }
    },
    (google.api.field_behavior) = REQUIRED
  ];
  AuxData aux_data = 5;
}

message CheckOutput {
  message ActionEffect {
    cerbos.effect.v1.Effect effect = 1;
    string policy = 2;
    string scope = 3;
  }

  string request_id = 1;
  string resource_id = 2;
  map<string, ActionEffect> actions = 3;
  repeated string effective_derived_roles = 4;
  repeated cerbos.schema.v1.ValidationError validation_errors = 5;
  repeated OutputEntry outputs = 6;
}

message OutputEntry {
  string src = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Rule that matched to produce this output."
    example: "\"resource.expense.v1/acme#rule-001\""
  }];
  google.protobuf.Value val = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
    description: "Dynamic output, determined by user defined rule output."
    example: "\"some_string\""
  }];
}

message Resource {
  string kind = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string = {min_len: 1},
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Name of the resource kind being accessed."
      example: "\"album:photo\""
    }
  ];
  string policy_version = 2 [
    (buf.validate.field).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\""
    }
  ];
  string id = 3 [
    (buf.validate.field).required = true,
    (buf.validate.field).string = {min_len: 1},
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "ID of the resource instance"
      example: "\"XX125\""
    }
  ];
  map<string, google.protobuf.Value> attr = 4 [
    (buf.validate.field).map.keys = {
      string: {min_len: 1}
    },
    (buf.validate.field).map.values.required = true,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Kay-value pairs of contextual data about this resource that should be used during policy evaluation."
      example: "{\"owner\": \"bugs_bunny\"}"
    }
  ];
  string scope = 5 [
    (buf.validate.field).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 this resource belongs to. This is used for determining policy inheritance."
      pattern: "^([[:alnum:]][[:word:]\\-]*(\\.[[:word:]\\-]*)*)*$"
      example: "\"acme.corp\""
    }
  ];
}

message Principal {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {description: "A person or application attempting to perform the actions on the set of resources."}
  };
  string id = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string = {min_len: 1},
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "ID of the principal"
      example: "\"bugs_bunny\""
    }
  ];
  string policy_version = 2 [
    (buf.validate.field).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."
      example: "\"default\""
      pattern: "^[[:word:]]*$"
    }
  ];
  repeated string roles = 3 [
    (buf.validate.field).repeated = {
      unique: true
      min_items: 1
      items: {
        string: {min_len: 1}
      }
    },
    (buf.validate.field).required = true,
    (google.api.field_behavior) = REQUIRED,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Roles assigned to this principal from your identity management system."
      min_items: 1
      unique_items: true
      example: "[\"user\"]"
    }
  ];
  map<string, google.protobuf.Value> attr = 4 [
    (buf.validate.field).map.keys = {
      string: {min_len: 1}
    },
    (buf.validate.field).map.values.required = true,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Key-value pairs of contextual data about this principal that should be used during policy evaluation."
      example: "{\"beta_tester\": true}"
    }
  ];
  string scope = 5 [
    (buf.validate.field).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 this principal belongs to. This is used for determining policy inheritance."
      pattern: "^([[:alnum:]][[:word:]\\-]*(\\.[[:word:]\\-]*)*)*$"
      example: "\"acme.corp\""
    }
  ];
}

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

  map<string, google.protobuf.Value> jwt = 1;
}

message Trace {
  message Component {
    enum Kind {
      KIND_UNSPECIFIED = 0;
      KIND_ACTION = 1;
      KIND_CONDITION_ALL = 2;
      KIND_CONDITION_ANY = 3;
      KIND_CONDITION_NONE = 4;
      KIND_CONDITION = 5;
      KIND_DERIVED_ROLE = 6;
      KIND_EXPR = 7;
      KIND_POLICY = 8;
      KIND_RESOURCE = 9;
      KIND_RULE = 10;
      KIND_SCOPE = 11;
      KIND_VARIABLE = 12;
      KIND_VARIABLES = 13;
      KIND_OUTPUT = 14;
      KIND_ROLE_POLICY_SCOPE = 15;
    }

    message Variable {
      string name = 1;
      string expr = 2;
    }

    Kind kind = 1;
    oneof details {
      string action = 2;
      string derived_role = 3;
      string expr = 4;
      uint32 index = 5;
      string policy = 6;
      string resource = 7;
      string rule = 8;
      string scope = 9;
      Variable variable = 10;
      string output = 11;
      string role_policy_scope = 12;
    }
  }

  message Event {
    enum Status {
      STATUS_UNSPECIFIED = 0;
      STATUS_ACTIVATED = 1;
      STATUS_SKIPPED = 2;
    }

    Status status = 1;
    cerbos.effect.v1.Effect effect = 2;
    string error = 3;
    string message = 4;
    google.protobuf.Value result = 5;
  }

  repeated Component components = 1;
  Event event = 2;
}

// Data from the request, provided to expressions as the top-level `request` variable.
message Request {
  message Principal {
    string id = 1;
    repeated string roles = 2;
    map<string, google.protobuf.Value> attr = 3;
    string policy_version = 4;
    string scope = 5;
  }

  message Resource {
    string kind = 1;
    string id = 2;
    map<string, google.protobuf.Value> attr = 3;
    string policy_version = 4;
    string scope = 5;
  }

  Principal principal = 1;
  Resource resource = 2;
  AuxData aux_data = 3;
}

// Data from the runtime, provided to expressions as the top-level `runtime` variable.
message Runtime {
  repeated string effective_derived_roles = 1;
}