syntax = "proto3";
package authzed.api.v1;

option go_package = "github.com/authzed/authzed-go/proto/authzed/api/v1";
option java_package = "com.authzed.api.v1";
option java_multiple_files = true;

import "google/protobuf/struct.proto";
import "validate/validate.proto";

// Relationship specifies how a resource relates to a subject. Relationships
// form the data for the graph over which all permissions questions are
// answered.
message Relationship {
  // resource is the resource to which the subject is related, in some manner
  ObjectReference resource = 1 [ (validate.rules).message.required = true ];

  // relation is how the resource and subject are related.
  string relation = 2 [ (validate.rules).string = {
    pattern : "^[a-z][a-z0-9_]{1,62}[a-z0-9]$",
    max_bytes : 64,
  } ];

  // subject is the subject to which the resource is related, in some manner.
  SubjectReference subject = 3 [ (validate.rules).message.required = true ];

  // optional_caveat is a reference to a the caveat that must be enforced over the relationship
  ContextualizedCaveat optional_caveat = 4 [ (validate.rules).message.required = false ];
}

// ContextualizedCaveat represents a reference to a caveat to be used by caveated relationships.
// The context consists of key-value pairs that will be injected at evaluation time.
// The keys must match the arguments defined on the caveat in the schema.
message ContextualizedCaveat {
  // caveat_name is the name of the caveat expression to use, as defined in the schema
  string caveat_name = 1 [ (validate.rules).string = {
    pattern : "^([a-zA-Z0-9_][a-zA-Z0-9/_|-]{0,127})$",
    max_bytes : 128,
  } ];

  // context consists of any named values that are defined at write time for the caveat expression
  google.protobuf.Struct context = 2 [ (validate.rules).message.required = false ];
}

// SubjectReference is used for referring to the subject portion of a
// Relationship. The relation component is optional and is used for defining a
// sub-relation on the subject, e.g. group:123#members
message SubjectReference {
  ObjectReference object = 1 [ (validate.rules).message.required = true ];
  string optional_relation = 2 [ (validate.rules).string = {
    pattern : "^([a-z][a-z0-9_]{1,62}[a-z0-9])?$",
    max_bytes : 64,
  } ];
}

// ObjectReference is used to refer to a specific object in the system.
message ObjectReference {
  string object_type = 1 [ (validate.rules).string = {
    pattern : "^([a-z][a-z0-9_]{1,61}[a-z0-9]/)*[a-z][a-z0-9_]{1,62}[a-z0-9]$",
    max_bytes : 128,
  } ];
  string object_id = 2 [ (validate.rules).string = {
    pattern : "^(([a-zA-Z0-9/_|\\-=+]{1,})|\\*)$",
    max_bytes : 1024,
  } ];
}

// ZedToken is used to provide causality metadata between Write and Check
// requests.
//
// See the authzed.api.v1.Consistency message for more information.
message ZedToken {
  string token = 1 [ (validate.rules).string = {
    min_bytes : 1,
  } ];
}

// Cursor is used to provide resumption of listing between calls to APIs
// such as LookupResources.
message Cursor {
  string token = 1 [ (validate.rules).string = {
    min_bytes : 1,
    max_bytes : 102400,
  } ];
}


// RelationshipUpdate is used for mutating a single relationship within the
// service.
//
// CREATE will create the relationship only if it doesn't exist, and error
// otherwise.
//
// TOUCH will upsert the relationship, and will not error if it
// already exists.
//
// DELETE will delete the relationship. If the relationship does not exist,
// this operation will no-op.
message RelationshipUpdate {
  enum Operation {
    OPERATION_UNSPECIFIED = 0;
    OPERATION_CREATE = 1;
    OPERATION_TOUCH = 2;
    OPERATION_DELETE = 3;
  }
  Operation operation = 1 [ (validate.rules).enum = {defined_only: true, not_in: [0]} ];
  Relationship relationship = 2 [ (validate.rules).message.required = true ];
}

// PermissionRelationshipTree is used for representing a tree of a resource and
// its permission relationships with other objects.
message PermissionRelationshipTree {
  oneof tree_type {
    option (validate.required) = true;

    AlgebraicSubjectSet intermediate = 1;
    DirectSubjectSet leaf = 2;
  }
  ObjectReference expanded_object = 3;
  string expanded_relation = 4;
}

// AlgebraicSubjectSet is a subject set which is computed based on applying the
// specified operation to the operands according to the algebra of sets.
//
// UNION is a logical set containing the subject members from all operands.
//
// INTERSECTION is a logical set containing only the subject members which are
// present in all operands.
//
// EXCLUSION is a logical set containing only the subject members which are
// present in the first operand, and none of the other operands.
message AlgebraicSubjectSet {
  enum Operation {
    OPERATION_UNSPECIFIED = 0;
    OPERATION_UNION = 1;
    OPERATION_INTERSECTION = 2;
    OPERATION_EXCLUSION = 3;
  }

  Operation operation = 1 [ (validate.rules).enum = {defined_only: true, not_in: [0]} ];
  repeated PermissionRelationshipTree children = 2 [ (validate.rules).repeated.items.message.required = true ];
}

// DirectSubjectSet is a subject set which is simply a collection of subjects.
message DirectSubjectSet { repeated SubjectReference subjects = 1; }

// PartialCaveatInfo carries information necessary for the client to take action
// in the event a response contains a partially evaluated caveat
message PartialCaveatInfo {
  // missing_required_context is a list of one or more fields that were missing and prevented caveats
  // from being fully evaluated
  repeated string missing_required_context = 1 [(validate.rules).repeated.min_items = 1];
}