proto/caosdb/CMakeLists.txt

@@ -21,6 +21,7 @@
 set(CAOSDB_API_PACKAGES
     caosdb.info.v1
     caosdb.entity.v1
+    caosdb.acm.v1alpha1
     )
 
 # pass variable to parent scope

proto/caosdb/acm/v1alpha1/main.proto

+//
+// This file is a part of the CaosDB Project.
+//
+// Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com>
+// Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+//
+
+// This is the main file of the caosdb.acm.v1alpha1 package.
+syntax                     = "proto3";
+option java_multiple_files = true;
+option java_package        = "org.caosdb.api.acm.v1alpha1";
+
+package caosdb.acm.v1alpha1;
+
+///////////////////////////////////////////
+// COMMON MESSAGES
+///////////////////////////////////////////
+
+// Client preferences for the paging. The server MUST respect the index
+// property or send the complete result set. The server MAY choose to send a
+// different page length in the response
+message PagingRequest {
+  // Desired index of the first element in the response. The index depends on
+  // the order of the elements in the result set.
+  int32 index = 1;
+  // Desired length of the page in the server response.
+  int32 page_length = 2;
+}
+
+// The actual paging of the response.
+message PagingResponse {
+  // Total numbers of results.
+  int32 total_number = 1;
+  // Index of the first item in the page.
+  int32 current_index = 2;
+}
+
+///////////////////////////////////////////
+// PERMISSSIONS
+///////////////////////////////////////////
+
+// Request to list all known permissions (excluding entity permissions).
+message ListKnownPermissionsRequest {}
+
+// Response with all known permissions. Clients may choose to create drop-down
+// menues from this list.
+message ListKnownPermissionsResponse {
+  // known permissions
+  repeated PermissionDescription permissions = 1;
+}
+
+// Description of a permission.
+message PermissionDescription {
+  // The permission
+  string permission = 1;
+  // The description
+  string description = 2;
+}
+
+// PermissionRule. These belong to Roles.
+message PermissionRule {
+  // The permission which is being granted oder denied.
+  string permission = 1;
+  // Priority permission rules (TRUE) overrule non-priority (FALSE) permission
+  // rules.
+  bool priority = 2;
+  // True means that the permission is being granted by this rule, false means
+  // the permission is being DENIED!
+  bool grant = 3;
+}
+
+///////////////////////////////////////////
+// ROLES
+///////////////////////////////////////////
+
+// Role
+message Role {
+  // Unique name of this role.
+  string name = 1;
+  // Description of the purpose of this role or which group of users this role
+  // represents.
+  string description = 2;
+  // List of permission rules for this role.
+  repeated PermissionRule permission_rules = 3;
+}
+
+// Request message for the ListRoles RPC
+message ListRolesRequest {
+  // Desired paging settings for the response.
+  PagingRequest paging = 1;
+}
+
+// Response message for the ListRoles RPC
+message ListRolesResponse {
+  // Actual paging setting of the response.
+  PagingResponse paging = 1;
+  // A subset (when paging is used) or the complete set (otherwise) of roles.
+  repeated ListRoleItem roles = 2;
+}
+
+// Combines role, the role's capabilities and the current users permissions.
+message ListRoleItem {
+  // Role
+  Role role = 1;
+  // The permissions of the user of the current session w.r.t. this role.
+  repeated RolePermissions permissions = 2;
+  // What can be done with this role.
+  repeated RoleCapabilities capabilities = 3;
+}
+
+// Request message for the CreateSingleRole RPC
+message CreateSingleRoleRequest {
+  // The new role.
+  Role role = 1;
+}
+
+// Response message for the CreateSingleRole RPC
+message CreateSingleRoleResponse {}
+
+// Request message for the RetrieveSingleRole RPC
+message RetrieveSingleRoleRequest {
+  // the name of the role.
+  string name = 1;
+}
+
+// Response message for the RetrieveSingleRole RPC
+message RetrieveSingleRoleResponse {
+  // The role.
+  Role role = 1;
+  // Known users with this role
+  repeated User users = 2;
+  // The permissions of the user of the current session w.r.t. this role.
+  repeated RolePermissions permissions = 3;
+  // What can be do with this role.
+  repeated RoleCapabilities capabilities = 4;
+}
+
+// Request message for the UpdateSingleRole RPC
+message UpdateSingleRoleRequest {
+  // The role
+  Role role = 1;
+}
+// Response message for the UpdateSingleRole RPC
+message UpdateSingleRoleResponse {}
+
+// Request message for the DeleteSingleRole RPC
+message DeleteSingleRoleRequest {
+  // the name of the role.
+  string name = 1;
+}
+
+// Response message for the DeleteSingleRole RPC
+message DeleteSingleRoleResponse {}
+
+// Role Permissions
+enum RolePermissions {
+  // Unspecified permission
+  ROLE_PERMISSIONS_UNSPECIFIED = 0;
+  // Role can be deleted
+  ROLE_PERMISSIONS_DELETE = 1;
+  // Description can be updated
+  ROLE_PERMISSIONS_UPDATE_DESCRIPTION = 2;
+  // Permission rules of this role can be updated
+  ROLE_PERMISSIONS_UPDATE_PERMISSION_RULES = 3;
+  // This role can be assigned
+  ROLE_PERMISSIONS_ASSIGN = 4;
+}
+
+// Role Capabilities
+enum RoleCapabilities {
+  // Unspecified capability
+  ROLE_CAPABILITIES_UNSPECIFIED = 0;
+  // This role is deletable
+  ROLE_CAPABILITIES_DELETE = 1;
+  // This role's permissions can be changed
+  ROLE_CAPABILITIES_UPDATE_PERMISSION_RULES = 2;
+  // This role can be assigned to a user
+  ROLE_CAPABILITIES_ASSIGN = 3;
+}
+
+///////////////////////////////////////////
+// USERS
+///////////////////////////////////////////
+
+// UserStatus
+enum UserStatus {
+  // The user status is unspecified/unknown.
+  USER_STATUS_UNSPECIFIED = 0;
+  // The user is inactive and cannot sign in.
+  USER_STATUS_INACTIVE = 1;
+  // The user is active and can sign in.
+  USER_STATUS_ACTIVE = 2;
+}
+
+// PasswordSetting - it is handy to have this as a separate message b/c
+// otherwise we could not distinguish between empty string and an unspecified
+// password.
+message PasswordSetting {
+  // The password
+  string password = 1;
+}
+
+// EmailSetting - it is handy to have this as a separate message b/c otherwise
+// we could not distinguish between empty string and an unspecified email.
+message EmailSetting {
+  // The email adress
+  string email = 1;
+}
+
+// EntitySetting - it is handy to have this as a separate message b/c otherwise
+// we could not distinguish between empty string and an unspecified entity.
+message EntitySetting {
+  // The entity which represents this user (e.g. a Person or Device Record).
+  string entity_id = 1;
+}
+
+// User
+message User {
+  // Indicates whether the user is active. Only active users can sign in and
+  // interact with the CaosDB Server.
+  UserStatus status = 1;
+  // Realm of this user. The realm is the authority which can authenticate this
+  // user, e.g. 'PAM' when the user is a (POSIX) user from the server's host, or
+  // 'CaosDB' when CaosDB server itself can authenticate the user.
+  string realm = 2;
+  // Name of this user.
+  string name = 3;
+  // Email setting of this user.
+  EmailSetting email_setting = 4;
+  // Entity setting of this user.
+  EntitySetting entity_setting = 5;
+  // List of roles of this user.
+  repeated string roles = 6;
+}
+
+// Request message for the ListUsers RPC.
+message ListUsersRequest {
+  // Desired paging settings for the response.
+  PagingRequest paging = 1;
+}
+
+// Response message for the ListUsers RPC.
+message ListUsersResponse {
+  // Actual paging setting of the response.
+  PagingResponse paging = 1;
+  // A subset (when paging is used) or the complete set (otherwise) of known
+  // users.
+  repeated User users = 2;
+}
+
+// Request message for the CreateSingleUser RPC
+message CreateSingleUserRequest {
+  // The new user.
+  User user = 1;
+  // The new password.
+  PasswordSetting password_setting = 2;
+}
+
+// Response message for the CreateSingleUser RPC
+message CreateSingleUserResponse {}
+
+// Request message for the RetrieveSingleUser RPC
+message RetrieveSingleUserRequest {
+  // The user's realm
+  string realm = 1;
+  // The user's name
+  string name = 2;
+}
+
+// Response message for the RetrieveSingleUser RPC
+message RetrieveSingleUserResponse {
+  // The user
+  User user = 1;
+  // The permissions of the user of the current session.
+  repeated UserPermissions permissions = 2;
+  // What can be done with this user
+  repeated UserCapabilities capabilities = 3;
+}
+
+// Request message for the UpdateSingleUser RPC
+message UpdateSingleUserRequest {
+  // The new user.
+  User user = 1;
+  // The new password. Password will not be updated when this is unset.
+  PasswordSetting password_setting = 2;
+}
+
+// Response message for the UpdateSingleUser RPC
+message UpdateSingleUserResponse {}
+
+// Request message for the DeleteSingleUser RPC
+message DeleteSingleUserRequest {
+  // The user's realm
+  string realm = 1;
+  // The user's name
+  string name = 2;
+}
+
+// Response message for the DeleteSingleUser RPC
+message DeleteSingleUserResponse {}
+
+// Permissions for updating and deleting a user.
+enum UserPermissions {
+  // Unspecified permission
+  USER_PERMISSIONS_UNSPECIFIED = 0;
+  // The user can be deleted.
+  USER_PERMISSIONS_DELETE = 1;
+  // The password of the user can be updated.
+  USER_PERMISSIONS_UPDATE_PASSWORD = 2;
+  // The email of the user can be updated.
+  USER_PERMISSIONS_UPDATE_EMAIL = 3;
+  // The status (active/inactive) of the user can be changed.
+  USER_PERMISSIONS_UPDATE_STATUS = 4;
+  // The roles of the user can be altered.
+  USER_PERMISSIONS_UPDATE_ROLES = 5;
+  // Ths entity of the user can be set.
+  USER_PERMISSIONS_UPDATE_ENTITY = 6;
+}
+
+// What can be done with a user (generally speaking, if permissions suffice).
+enum UserCapabilities {
+  // Unspecified capability
+  USER_CAPABILITIES_UNSPECIFIED = 0;
+  // User can be deleted.
+  USER_CAPABILITIES_DELETE = 1;
+  // The user's password can be updated.
+  USER_CAPABILITIES_UPDATE_PASSWORD = 2;
+}
+
+///////////////////////////////////////////
+// SERVICE DEFINITION
+///////////////////////////////////////////
+
+// A service for managing the access to the CaosDB Server via user accounts,
+// roles and permissions.
+service AccessControlManagementService {
+  // Request the list of known users.
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {};
+
+  // Retrieve a single user
+  rpc RetrieveSingleUser(RetrieveSingleUserRequest)
+      returns (RetrieveSingleUserResponse) {};
+
+  // Create a single new user
+  rpc CreateSingleUser(CreateSingleUserRequest)
+      returns (CreateSingleUserResponse) {};
+
+  // Update a single user
+  rpc UpdateSingleUser(UpdateSingleUserRequest)
+      returns (UpdateSingleUserResponse) {};
+
+  // Delete a single user
+  rpc DeleteSingleUser(DeleteSingleUserRequest)
+      returns (DeleteSingleUserResponse) {};
+
+  // Request the list of roles.
+  rpc ListRoles(ListRolesRequest) returns (ListRolesResponse) {};
+
+  // Retrieve a single role
+  rpc RetrieveSingleRole(RetrieveSingleRoleRequest)
+      returns (RetrieveSingleRoleResponse) {};
+
+  // Create a single new role
+  rpc CreateSingleRole(CreateSingleRoleRequest)
+      returns (CreateSingleRoleResponse) {};
+
+  // Update a single role
+  rpc UpdateSingleRole(UpdateSingleRoleRequest)
+      returns (UpdateSingleRoleResponse) {};
+
+  // Delete a single role
+  rpc DeleteSingleRole(DeleteSingleRoleRequest)
+      returns (DeleteSingleRoleResponse) {};
+
+  // List all known permissions
+  rpc ListKnownPermissions(ListKnownPermissionsRequest)
+      returns (ListKnownPermissionsResponse) {};
+}

proto/caosdb/entity/v1/main.proto

@@ -691,11 +691,143 @@ message MultiTransactionResponse {
   repeated Message transaction_infos = 4;
 }
 
+// Request of the MultiRetrieveEntityACL rpc
+message MultiRetrieveEntityACLRequest {
+  // The requested entity ids.
+  repeated string id = 1;
+}
+
+// Response of the MultiRetrieveEntityACL rpc
+message MultiRetrieveEntityACLResponse {
+  // The entities ACLs
+  repeated EntityACL acls = 1;
+}
+
+// Request of the MultiUpdateEntityACL rpc
+message MultiUpdateEntityACLRequest {
+  // The requested entity ids.
+  repeated EntityACL acls = 1;
+}
+
+// Response of the MultiUpdateEntityACL rpc
+message MultiUpdateEntityACLResponse {}
+
+// Entity Access Controll List (ACL)
+message EntityACL {
+  // The entity id
+  string id = 1;
+  // The rules which make up the ACL
+  repeated EntityPermissionRule rules = 2;
+  // relevant permissions of the current session, e.g. if the current user is
+  // allowed to update the ACL. This is read-only and will be ignored by the
+  // server.
+  EntityAclPermission permission = 3;
+}
+
+// Entity ACL Permission indicates whether the current user is allowed to update
+// the Entity's ACL.
+enum EntityAclPermission {
+  // UNSPECIFIED, effectively means "NO"
+  ENTITY_ACL_PERMISSION_UNSPECIFIED = 0;
+  // Non-priority rules may be edited.
+  ENTITY_ACL_PERMISSION_EDIT_ACL = 1;
+  // Priority and non-priority rules may be edited.
+  ENTITY_ACL_PERMISSION_EDIT_PRIORITY_ACL = 2;
+}
+
+// Permission rules for Entity ACL
+message EntityPermissionRule {
+  // The role for which this rule applies
+  string role = 1;
+  // Is priority?
+  bool priority = 2;
+  // Is grant?
+  bool grant = 3;
+  // permissions
+  repeated EntityPermission permissions = 4;
+  // capabilities
+  repeated EntityPermissionRuleCapability capabilities = 5;
+}
+
+// What (given enough permissions) can be done with an EntityPermissionRule.
+// E.g. globel entity permission rules, which are to be specified in a
+// configuration file cannot be deleted, thus they are missing the
+// ENTITY_PERMISSION_RULE_CAPABILITY_DELETE capability.
+enum EntityPermissionRuleCapability {
+  // Unspecified capability.
+  ENTITY_PERMISSION_RULE_CAPABILITY_UNSPECIFIED = 0;
+  // This permission rule can be deleted/removed from the ACL
+  ENTITY_PERMISSION_RULE_CAPABILITY_DELETE = 1;
+}
+
+// Entity permissions
+enum EntityPermission {
+  // Unspecified permission.
+  ENTITY_PERMISSION_UNSPECIFIED = 0;
+  // Permission to retrieve the full entity (name, description, data type, ...)
+  // with all parents and properties (unless prohibited by another rule on the
+  // property level).
+  ENTITY_PERMISSION_RETRIEVE_ENTITY = 1;
+  // Permission to retrieve the full and final ACL of this entity.
+  ENTITY_PERMISSION_RETRIEVE_ACL = 2;
+  // Permission to retrieve the history of this entity.
+  ENTITY_PERMISSION_RETRIEVE_HISTORY = 3;
+  // Permission to retrieve the owner(s) of this entity.
+  ENTITY_PERMISSION_RETRIEVE_OWNER = 4;
+  // Permission to download the file belonging to this entity.
+  ENTITY_PERMISSION_RETRIEVE_FILE = 5;
+  // Permission to delete an entity.
+  ENTITY_PERMISSION_DELETE = 6;
+  // Permission to change the user-specified part of this entity's ACL. Roles
+  // with this Permission are called 'Owners'.
+  ENTITY_PERMISSION_EDIT_ACL = 7;
+  // Permission to change the value of this entity.
+  ENTITY_PERMISSION_UPDATE_DESCRIPTION = 8;
+  // Permission to change the value of this entity.
+  ENTITY_PERMISSION_UPDATE_VALUE = 9;
+  // Permission to change the role of this entity.
+  ENTITY_PERMISSION_UPDATE_ROLE = 10;
+  // Permission  to remove parents from this entity.
+  ENTITY_PERMISSION_UPDATE_REMOVE_PARENT = 11;
+  // Permission to add a parent to this entity.
+  ENTITY_PERMISSION_UPDATE_ADD_PARENT = 12;
+  // Permission to remove properties from this entity.
+  ENTITY_PERMISSION_UPDATE_REMOVE_PROPERTY = 13;
+  // Permission to add a property to this entity.
+  ENTITY_PERMISSION_UPDATE_ADD_PROPERTY = 14;
+  // Permission to change the name of this entity.
+  ENTITY_PERMISSION_UPDATE_NAME = 15;
+  // Permission to change the data type of this entity.
+  ENTITY_PERMISSION_UPDATE_DATA_TYPE = 16;
+  // Permission to delete the file of this entity.
+  ENTITY_PERMISSION_UPDATE_REMOVE_FILE = 17;
+  // Permission to set a file for this entity.
+  ENTITY_PERMISSION_UPDATE_ADD_FILE = 18;
+  // Permission to move an existing file to a new location.
+  ENTITY_PERMISSION_UPDATE_MOVE_FILE = 19;
+  // Permission to refer to this entity via a reference property.
+  ENTITY_PERMISSION_USE_AS_REFERENCE = 20;
+  // Permission to implement this entity as a property.
+  ENTITY_PERMISSION_USE_AS_PROPERTY = 21;
+  // Permission to use this entity as a super type for other entities.
+  ENTITY_PERMISSION_USE_AS_PARENT = 22;
+  // Permission to use this entity as a data type for reference properties.
+  ENTITY_PERMISSION_USE_AS_DATA_TYPE = 23;
+  // Permission to update the query template definition of this QueryTemplate
+  ENTITY_PERMISSION_UPDATE_QUERY_TEMPLATE_DEFINITION = 24;
+}
+
 // Entity Transaction Service
 service EntityTransactionService {
   // Issue multiple mixed requests
   rpc MultiTransaction(MultiTransactionRequest)
       returns (MultiTransactionResponse);
+  // Request the Entity ACLs
+  rpc MultiRetrieveEntityACL(MultiRetrieveEntityACLRequest)
+      returns (MultiRetrieveEntityACLResponse);
+  // Set the Entity ACLs,
+  rpc MultiUpdateEntityACL(MultiUpdateEntityACLRequest)
+      returns (MultiUpdateEntityACLResponse);
 }
 
 ///////////////////////////////////////////////////////////////////////////

proto/caosdb/info/v1/main.proto

@@ -25,6 +25,8 @@ option java_package        = "org.caosdb.api.info.v1";
 
 package caosdb.info.v1;
 
+/////////////////////////////// SERVER VERSION
+
 // The version of an agent (following SemVer 2.0.0)
 message VersionInfo {
   // Major version number
@@ -48,8 +50,29 @@ message GetVersionInfoResponse {
   VersionInfo version_info = 1;
 }
 
+////////////////////////// SESSION
+
+// Request message for the GetSessionInfo RPC
+message GetSessionInfoRequest {}
+
+// Response message for the GetSessionInfo RPC
+message GetSessionInfoResponse {
+  // The realm of the user who owns this session
+  string realm = 1;
+  // The name of the user who owns this session
+  string username = 2;
+  // The roles of the user who owns this session
+  repeated string roles = 3;
+  // Seconds until this sessions expires (approximately).
+  int64 expires = 4;
+  // The permissions of the user who owns this sessions
+  repeated string permissions = 5;
+}
+
 // A service which provides general information about the server.
 service GeneralInfoService {
   // Request the detailed version information from the server.
   rpc GetVersionInfo(GetVersionInfoRequest) returns (GetVersionInfoResponse) {};
+  // Request information about the current session (user, roles, timeout...).
+  rpc GetSessionInfo(GetSessionInfoRequest) returns (GetSessionInfoResponse) {};
 }