Add overview docs for user auth (login + permissions)

docs/data/auth.rst

@@ -0,0 +1,172 @@
+
+User Auth
+=========
+
+Rattail of course includes the concept of a "user" account.  In
+general the purpose this serves is 2-fold:
+
+* restrict access to certain parts of the app
+* provide attribution, e.g. "who did what (and when)"
+
+
+Overview
+--------
+
+Rattail has a User table, which contains the basic account record.  It
+is quite minimal but a User can relate to a Person, and then
+indirectly a Customer etc.
+
+User records then are associated to a great many other things,
+e.g. when a user creates a new batch, their user account is associated
+with that batch.
+
+User accounts do not themselves, directly, have "permission" to do
+anything.  But a User may belong to zero or more Roles, which then
+grant it permission to do things.  (Even if zero, the special
+"Authenticated" role may automatically grant some permissions; more on
+that below.)
+
+
+Authentication (aka. Login)
+---------------------------
+
+Normally each person who "logs in" to Rattail must already have a User
+account.  The login succeeds if they supply correct username and
+password, both of which are stored in the User account (with the
+password being encrypted).
+
+Additionally, the User account may be marked "inactive" by the admin; if
+so then login will not be allowed for that user.
+
+Customization is possible, for instance to check credentials against
+Active Directory or your POS system etc.  User accounts may even be
+auto-created on first login etc.
+
+
+Authorization (aka. Permissions)
+--------------------------------
+
+Rattail has a Role table, to define various user roles.  The admin can
+create new roles as needed, to reflect the organizational realities
+etc.
+
+Permissions then are granted to (or revoked from) the various roles
+which are defined.  If a permission is "attached" to the role, then
+the role "has" it, otherwise not.
+
+Users then may be associated with zero or more roles, and they inherit
+the full set of permissions from all roles to which they belong.
+
+
+Special Roles
+~~~~~~~~~~~~~
+
+There are 3 special roles which come built-in:
+
+
+.. _admin_role:
+
+Administrator
++++++++++++++
+
+This role is special for obvious reasons.  
+
+Only users who belong to this role, can "become root" (see
+:ref:`becoming_root`).
+
+Other than that though, the role behaves normally.  For instance if
+you are the admin user and only belong to this role, then you will
+normally see only those things which are included in this role's
+permissions (unless you become root of course).  
+
+Permissions for this role may be edited as for any other role.
+Although there is a chance that you must "become root" to do so; that
+is normal and not something that requires fixing per se.
+
+
+Guest
++++++
+
+This "guest" role is really "anonymous" - i.e. any "user" who is
+actively using the system but has not logged in, falls into this role
+automatically.
+
+Permissions for this role may be edited as for any other role.  But
+they will apply *only* to users who are not logged in.
+
+
+.. _auth_role:
+
+Authenticated
++++++++++++++
+
+This role automatically applies to any user who *has* logged in,
+regardless of any other roles the user may belong to.
+
+Permissions for this role may be edited as for any other role.  They
+will apply to anyone who has logged in.
+
+
+.. _becoming_root:
+
+Becoming Root
+~~~~~~~~~~~~~
+
+Any user who belongs to the special Administrator role (see
+:ref:`admin_role`) - and *only* users in that role - are automatically
+granted permission to "become root" when they are logged in.
+
+Becoming root is similar in spirit to the ``su`` command in Unix.
+Basically when you become root, all normal permission checks are
+bypassed; you can do anything "supported" by the system.  Note that
+the term "supported" is used loosely here, and just means whatever the
+code can "literally" do.  (Some of which may be bad for your system!)
+
+So of course be careful with this, it can be quite handy but if you
+find yourself "frequently" using it to access some feature, you
+probably should just grant permission for that feature to the
+Administrator role, and then you can stop having to become root all
+the time!  (Which helps to avoid doing something bad by accident.)
+
+
+Syncing Users & Roles
+---------------------
+
+Users and roles are closely related, but how (and/or whether) they are
+synced across app nodes, is handled differently.
+
+
+Users
+~~~~~
+
+By default all users are synced across all nodes; simple as that.
+
+It is possible however to mark a user account as "local only" - which
+will cause that particular user to *not* be synced to other nodes; it
+will exist only in the current node.
+
+
+Roles
+~~~~~
+
+By default *no* roles are synced across nodes; each is "local only"
+effectively.
+
+It is possible however to mark a role as "synced" - which will cause
+that role to be synced across all nodes.
+
+In a multi-node system it is likely that there are different "types"
+of nodes.  In such a system it may be useful to sync certain roles,
+but have them only "apply" to certain node types.  (The roles must
+exist in all nodes for sync to work properly, but need only apply to
+certain nodes.)
+
+If a role is synced, then not only its primary attributes (e.g. name)
+will be synced, but also its user "membership" list as well as its
+permission list.
+
+The main use case here is in a multi-store setup, where you have one
+"host" node and two or more "store" nodes.  You can create a role with
+node type of "store" and flag it for sync.  The role will be synced
+along with its users and permissions, but will only be actually *used*
+on the store nodes.

docs/data/index.rst

@@ -9,6 +9,7 @@ Data Layer
    db/index
    trainwreck
    other
+   auth
    importing/index
    sync
    versioning