principal.proto

// Copyright 2021 The Cockroach Authors.
//
// 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
//   http://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.

syntax = "proto3";
package cacheroach.principal;
import "capabilities.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
option go_package = "github.com/bobvawter/cacheroach/api/principal";

message ID {
  bytes data = 1;
}

enum TokenStatus {
  // The token has not (yet) been validated.
  UNKNOWN = 0;
  // The token should be considered valid until the refresh_after time.
  VALID = 1;
  // The token is being refreshed by another instance.  It should be
  // considered valid until the listed refresh time, at which point it
  // should be refreshed again.
  REFRESHING = 2;
  // The token could not be revalidated and no further attempts should
  // be made.
  PERMANENT_FAILURE = 3;
}

message Principal {
  option (capabilities.msg_rule).or = {
    rule: {direction: RESPONSE}
    rule: {
      message: "must be able to read the principal"
      may: {
        capabilities: {read: true}
        scope: {on_principal: {field: 1}}
      }}
  };

  ID ID = 1;
  string label = 2;
  int64 version = 3;
  // OIDC claims as provided by an authentication server.
  bytes claims = 4 [
    (capabilities.field_rule) = {
      message: "must have pii access"
      or : {
        rule: {
          and: {
            rule: {direction: REQUEST}
            rule : {auth_status: SUPER}
          }
        }
        rule: {
          and: {
            rule: {direction: RESPONSE}
            rule: {may: {
              capabilities: {pii: true}
              scope: {on_principal: {field: 1}}
            }}
          }
        }
      }
    }
  ];
  // If present, indicates that the principal represents all users whose
  // email address are in the given domain.
  string email_domain = 5;
  string refresh_token = 66 [
    (capabilities.field_rule).never = true
  ];
  google.protobuf.Timestamp refresh_after = 67 [
    (capabilities.field_rule).never = true
  ];
  TokenStatus refresh_status = 68 [
    (capabilities.field_rule).never = true
  ];
}

message LoadRequest {
  oneof Kind {
    // Load a Principal based on ID.
    ID ID = 1;
    // Load a Principal by email address.
    string email = 2;
    // Load a domain-level Principal.
    string email_domain = 3;
  }
}

message WatchRequest {
  ID principal = 1;
  google.protobuf.Duration duration = 2;
}

message EnsureRequest {
  Principal principal = 1;
  bool delete = 2;
}

message EnsureResponse {
  Principal principal = 1;
}

service Principals {
  rpc Ensure (EnsureRequest) returns (EnsureResponse) {
    option idempotency_level = IDEMPOTENT;
  }
  rpc List (google.protobuf.Empty) returns (stream Principal) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
  rpc Load (LoadRequest) returns (Principal) {
    option idempotency_level = NO_SIDE_EFFECTS;
    option (capabilities.method_rule).auth_status = LOGGED_IN;
  }
  rpc Watch (WatchRequest) returns (stream Principal) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}