Fix institution and affiliation, role as group

Requirements/DBUser API.md

@@ -3,51 +3,58 @@
 
 This document is the requirements for the database user API, DBUser API. Eventually, there will be a
 corresponding document in Specifications. This document covers user data requirements as related to
-authentication and authorization (Au/Az).
+authentication and authorization (Au/Az) as well as user account information.
 
-For background about users, please see:
+For additional background about users, please see:
 
 [User Management Requirements](Requirements/User Management.md)
 
 ### What data and features must be provided
 
-- user must have a unique id, which we mint when creating the user database record in the database. The id is
+- User must have a unique id, which we mint when creating the user database record in the database. The id is
   supplied by the database as a record id, which is a unique integer. User must have a unique username, which
-  is some string; we currently use an email address for username
+  is some string; we currently use an email address for username.
 
-- support for data necessary to authenticate (log in), which is currently handled outside DBUser by
-  OpenID. This data includes an access token and expires time
+- Each user belongs to one or more roles, and roles have privileges, therefore users have privileges.
 
-- support for user authorization for specific system features. This requirement relies on privilege(s).
+- Support for data necessary to authenticate (log in), which is currently handled outside DBUser by
+  OpenID. This data includes an access token and expires time.
 
-- create user, requires a username which we default to the email address string. We also expect that the email
+- Support for user authorization for specific system features. This requirement relies on privilege(s).
+
+- Create user requires a username which we default to the email address string. We also expect that the email
   field will contain an email address. There was some discussion of multiple email addresses per user. That
   has not been implemented.
 
-- update user, all fields except the ID and username; ID must never be modified. Changing username will have
+- Update user, all fields except the ID and username; ID must never be modified. Changing username will have
   unpredictable consequences.
 
-- delete or inactivate user
+- Delete or inactivate user
+
+- Add privilege to user via adding a role
 
-- create privilege
+- Remove privilege from user via removing a role
 
-- add privilege to user
+- Multiple privileges per user via multiple roles
 
-- remove privilege from user
+- Create session
 
-- delete privilege (probably inadvisable, but we make it possible)
+- Extend session expiration time
 
-- allow multiple privileges per user
+- Add session to user
 
-- create session
+- Remove session from user
 
-- extend session expiration time
+- Remove all sessions from user
 
-- add session to user
+- List all users
 
-- remove session from user
+Beyond user data, the "authorization system" requires features of the DBUser API:
 
-- remove all sessions from user
+- Create, modify, list and generally manage roles via web admin
+
+- Create, modify, list and generally manage privileges in coordination with hard coded, symbolic references to
+  privileges, almost certainly only managed by developers.
 
 User id must be unique for all time, and thus, user ids may not be reused. We have a numerical unique user id
 internal to the system, which is the row id from table appuser. We added a textual username which
@@ -68,14 +75,18 @@ Each user has account info:
 
 - id (not editable, database assigned integer record id)
 - username, unique string, we currently use an email address string
+- affiliation, SNAC ID of the constellation of the affiliated institution
 - active (boolean)
 - first name
 - last name
 - full name
 - email, not unique
+- work email
+- work phone
 - avatar
 - avatar small
 - avatar large
+- preferred descriptive rules
 - password, stored hashed
 
 When logged in, a user has at least one "session", and the session has some associated data. We anticipate
@@ -86,19 +97,24 @@ Current session data includes:
 - access token from the authentication (OAuth?)
 - expiration time stamp when the session will expire
 
-The REST API requires the same session data. REST API users will have the same Au/Az constraints
+The REST API requires the same session data. REST API users will have the same Au/Az constraints.
+
+The system has privileges used to implement authorization in the code, extensively integrated throughout the
+DBUser API. Each user belongs to one or more roles, and roles have privileges, therefore users have
+privileges.
 
-The system has privileges conceptually, extensively integrated throughout the DBUser API. Each user is granted one
-or more privileges.  Each user has one or more privileges, as many as necessary.
 
 
 ### Privileges
 
-The SNAC permission system is based entirely on privileges (groups). SNAC is authorizing users to run various
-functions. Ownership is a non-concept, but essentially the system owns all functions. In a situation like SNAC
-where there is a single owner, the concept of "owner" has no utility in authorization. The Linux concept of
-"other" doesn't apply to SNAC as "other" is only allowed to perform read-only actions such as search. That
-leaves SNAC needing only a privilege system.
+The SNAC permission system is based entirely on privileges (permissions). Groups of privileges are
+roles. Privileges authorize users to run various functions. Ownership of a constellation is a non-concept, and
+essentially the system owns all functions. In a situation like SNAC where there is a single owner, the Linux
+concept of "owner" has no utility in authorization. The Linux concept of "other" doesn't apply to SNAC as
+"other" is only allowed to perform read-only actions such as search. That leaves SNAC needing only a privilege
+system analogous to Linux "group". Note that SNAC role would be analogous to a group of Linux groups.
+
+Note that affiliation is a property of each user account, and there is a single affiliation per user.
 
 (Optional paragraph) Not having "files", there is no concept of "file has no privileges" for user, group, or
 other. An example of what SNAC does not have is the shared web server situation where user grants privileges
@@ -115,13 +131,11 @@ In a global sense, the cumulative collection of users and privileges is complica
 essential (not accidental) and on a per-user or per-privilege basis, things are very manageable. When managing the
 system, imagine asking these typical, and manageable questions:
 
-- List all users affiliated with California Digital Library (CDL).
-
-- List all users affiliated with UC Irvine.
+- List all users affiliated with my affilation
 
 - List all users who can enroll new users for any affiliation
 
-- List all users who can only enroll new users for NYPL
+- List all users who can only enroll new users only for own-affiliation
 
 - List all users who can publish constellations.
 
@@ -136,44 +150,52 @@ that was simply redundant.
 
 The privileges below are real, but do not imply any actual policy or any relation to persons living or dead.
 
+Note that affiliation is a property of each user account, and there is a single affiliation per user.
+
 Pulling a couple of random details from the table below, and wording them in English:
 
-- Casey at CDL can approve NACO submissions (NACO approve)
-- Jessie at NYPL is limited to assigning privileges only for NYPL (affiliation-nypl and privilege-assign-own)
+- Casey at CDL can approve NACO submissions (NACO approve), modify constellations, change constellation
+  status, change owner/lock of constellations, and publish constellations.
+- Jessie at NYPL create new users affiliated with NYPL, run reports with NYPL constraints, and can assign
+  privileges only for NYPL (privilege-assign-own).
 
 
-| user             | description    | privileges                                                                                           |
-|------------------|----------------|-------------------------------------------------------------------------------------------------|
-| Marley Turner    | content expert | contribute, affiliation-none                                                                    |
-| Remy Roberts     | power editor   | contribute, change-status-any, change owner, publish, affiliation-any                           |
-| Casey Miyazaki   | editor CDL     | contribute, change-status-own, publish, NACO approve, affiliation-cdl, report-own-affiliation   |
-| Jessie Coughlin  | admin NYPL     | affiliation-nypl, enroll-own-affiliation report-own-affiliation, privilege-assign-own                |
-| Avery Valenzuela | super admin    | enroll-any, report-any, privilege-assign-any                                                         |
+| user             | description             | privileges                                                                   |
+|------------------+-------------------------+------------------------------------------------------------------------------|
+| Marley Turner    | content expert          | contribute,                                                                  |
+| Remy Roberts     | power editor            | contribute, change-status-any, change owner, publish,                        |
+| Casey Miyazaki   | editor, affiliation CDL | contribute, change-status-own, publish, NACO approve, report-own-affiliation |
+| Jessie Coughlin  | admin, affiliation NYPL | enroll-own-affiliation report-own-affiliation, privilege-assign-own          |
+| Avery Valenzuela | super admin             | enroll-any, report-any, privilege-assign-any                                 |
 
 
 Privileges have a number of traits.
 
-- Privileges are additive, and all privileges of a user define that user's authorized functions
-- Privileges are created and maintained by admins and developers.
-- Some instance privileges (such as affiliation) can be created by admins as needed.
-- Privileges (ideally) have a single privilege per privilege. Privileges are very granular.
-- Privileges and privileges must be coordinated with work flows and application features.
-- One privilege exists per institutional affiliation.
-- Every user has the conceptually privilege Public HRT, although no actual privilege exists for read-only access to published constellations
-- Potentially, we can have privileges for ad hoc groups (sub-institution, department, professional orgs, etc.)
+- Privileges are created and maintained by developers to authorize access to application features.
+- Every privilege grants authorization to specific application features, therefore privileges are maintained
+  only by developers.
+- Privileges are additive, and all privileges of a user define that user's authorized functions. Everything not
+  explicitly allowed is explicitly forbidden.
+- Privileges (ideally) have a single feature permission per privilege. Privileges are very granular.
+- Privileges must be coordinated with work flows and application features.
+- Privilege is independent of institutional affiliation.
+- Every user has the conceptually privilege Public HRT, although no actual privilege exists for read-only access to published constellations.
 - Privileges can be deprecated, but re-purposing privileges is inadvisable from a security standpoint.
 - Privileges need explicit, on-going policy guidance.
+- Privilege label must be unique since the code will almost certainly refer to privileges symbolically, that
+  is: by name, and the "name" of a privilege is the label field.
    
 
-The minimal privilege "Research" grants privileges for search history, and certain research reports.  Members of
-the public are mostly identical to Researchers. The primary feature gained by having an account is a
-persistent dashboard. As already noted, "Public HRT" not an actual privilege, but instead is conceptual.
+The minimal (implied?) privilege "Research" grants privileges for search history, and certain research
+reports.  Members of the public are mostly identical to Researchers. The primary feature gained by having an
+account is a persistent dashboard. As already noted, "Public HRT" not an actual privilege, but instead is
+conceptual and implicit.
 
 
 (Comment: I just noticed that privileges are mostly verbs: research, contribute, delete, propose, approve, block,
 embargo, enroll, assign. It seems like a nice idea to enshrine this as a convention. We would have to change
 "administrator" to "administer", and we need to come up with a verbs for the remaining privileges, especially
-"affiliation".)
+"own-affiliation".)
 
 Note that privileges are granualar, and each privilege must exist only once. Having one privilege does not
 imply having another. The Roles (a bit further below) deal with combinations of privileges.
@@ -188,9 +210,9 @@ imply having another. The Roles (a bit further below) deal with combinations of
 | Suggest edits (June 2016)        | Suggest edits, implies a mechanism to send suggestions to Edit             |
 | Publish (June 2016)              | Review, approve, publish, change status to "published"                     |
 | Change status any                | Change any status, removing locks, and so on, any affiliation              |
-| Change owner any                 | Change constellation user, changing which user has a lock, any affiliation |
+| Change owner (lock) any          | Change constellation user, changing which user has a lock, any affiliation |
 | Change status own                | Change any status, removing locks, and so on, own affiliation only         |
-| Change owner own                 | Change constellation user, changing user lock, own affiliation only        |
+| Change owner (lock) own          | Change constellation user, changing user lock, own affiliation only        |
 | Delete/embargo                   | Delete or embargo constellations  (editor)                                 |
 | Propose delete/embargo           | Propose delete or embargo                                                  |
 | Ontology propose                 | Propose headings in ontologies, but cannot approve headings                |
@@ -198,8 +220,8 @@ imply having another. The Roles (a bit further below) deal with combinations of
 | Propose NACO                     | Create(?) NACO contributions, but not push(?) to NACO                      |
 | Approve NACO                     | Approve, finalize, submit NACO contributions (editor)                      |
 | Enroll                           | Enroll new SNAC participants, create new users                             |
-| Privilege assign own institution | Assign new privileges for own-institution users                            |
-| Privilege assign any institution | Assign new privileges for any institution users                            |
+| Privilege assign own affiliation | Assign new privileges for own-institution users                            |
+| Privilege assign any affiliation | Assign new privileges for any institution users                            |
 | System administrator             | Maintains server hardware and operating systems                            |
 | Developer                        | Writes the SNAC application, a programmer                                  |
 | Web administrator                | (duplicate? historical?) May perform admin tasks via the web interface     |
@@ -208,23 +230,16 @@ imply having another. The Roles (a bit further below) deal with combinations of
 | Report own                       | Run own-institutional reports                                              |
 | Report any                       | Run any report, super reporter                                             |
 | Report admin                     | Run special administrative reports                                         |
-| Affiliation X                    | Affiliated with institution X.                                             |
-| Affiliation any                  | Affiliated with all institutions, a super privilege (discuss?)             |
+| Role admin                       | Create and modify roles. May be limited to devs.                           |
 
 
-### Example roles
-
-In order to make the system tractable and easy to talk about, we plan to allow privilege assigning admins to
-name groups of privileges. We are calling a privilege group a "role". There are two constraints on these names:
-
-1) Role name is unique within that institution. It would be confusing for more than one privilege group to
-have the same name.
 
-2) Because roles are grouped by institution, the same name may be used by another institution, perhaps for the
-same privilege, or perhaps for some totally different set of privileges.
+### Example roles
 
-Privilege names are fixed because they are universal to all of SNAC. If the policy team decides that Role is
-also a universal SNAC concept, that works fine within this conceptual framework.
+A group of privileges is a "role". Users are assigned roles, and the user gains all privileges in those
+roles. The authorization system only cares about privileges, so internal code will read the roles only to get
+the permissions. Roles exists to make the system tractable for admins. Role name is unique. It would be
+confusing for more than one role to have the same name.
 
 Remember, the table below is only a guess or approximation of real world roles. The software team is very much
 open to expanding the requirements to be as complete as possible. (Although not all requirements will
@@ -232,6 +247,8 @@ necessarily ever become features of SNAC.)
 
 #### Role table
 
+As of this writing, some roles have identical privileges. The duplicates should probably not exist.
+
 
 | Role                           | Privilege(s)                                        | User Description                                       |
 |--------------------------------+-----------------------------------------------------+--------------------------------------------------------|
@@ -245,21 +262,21 @@ necessarily ever become features of SNAC.)
 | Reviewer/editor                | Contribute + publish                                | Maintainer privileges, interacts with moderators       |
 | Editor in Training (June 2016) | Contribute                                          | Editor, no publish, training to be Editor              |
 | Contributor (June 2016)        | Simplified Create + Suggest Edits                   | Basic contributor, creator of constellations           |
-| Content expert                 | Contribute                                          | Domain expert, may have zero institutional privileges  |
+| Content expert                 | Contribute                                          | Domain expert, may have no affiliation                 |
 | Documentary editor             | Contribute                                          | (Any distinguishing privileges?)                       |
 | Maintenance                    | Contribute                                          | Constellation edit, maintain constellations.           |
 | Research                       | Research                                            | Use the discovery interface and history dashboard      |
 | Archival description donor     | Block upload                                        | May do bulk uploads of EAC-CPF, finding aids, etc.     |
 | Name authority manager         | Name authority                                      | (superseded by Editor-NACO?)                           |
-| Institutional admins           | Report own                                          | May run own-institutional reports                      |
+| Institutional admins           | Report own                                          | May run own-affiliation reports                        |
 | Public                         | n/a                                                 | No SNAC account, single session dashboard              |
 | Contributor                    | Contribute + Ontology propose                       | Creates/edit constellations, propose ontology headings |
 | Author                         | Contribute + Publish + Propose Del/Emb+Propose NACO | Contribute, with additional privileges                 |
 | Editor                         | Contribute + Publish + Delete/embargo + NACO        | Review constellations, approve and publish             |
 | Author-NACO                    | Propose NACO                                        | Creates NACO entries, sends to editor for submission   |
-| Administrator                  | Contributor + Editor privileges + enroll + assign   | Everything, only own institution                       |
-| Administrator-super            | Administrator + any institution                     | Admin+ assign privileges, any user, any institution    |
-|                                |                                                     |                                                        |
+| Administrator                  | Contributor + Editor privileges + enroll + assign   | Every admin, only own affiliation                      |
+| Administrator-super            | Administrator + any institution                     | Admin+ assign privileges, any user, any affiliation    |
+
 
 
 ### API