= !BluePrint for Authorization (alternative version) =

== General model ==

Authorization is implemented for:

  - module access
  - controller access
  - table access (create/read/update/delete and custom method)
  - record access (create/read/update/delete and custom method)

Authorization policy is implemented as:

  - if a method is not restricted, then it is accessible for everyone
  - if a method is restricted, then access must be explicitly granted, otherwise access is declined (Allow=>Deny order)

Permissions are assigned to roles (not to individual users):

  - roles are stored in auth_group
  - admin role is auth_group 1 (cannot be modified)
  - all methods on everything are allowed for members of the admin role
  - roles are assigned to users by auth_membership
  - roles can be created after deployment
  - roles of the actual user are re-read from the DB and stored in the session once per HTTP request

There are two pseudo-roles for record access:

  - author (=the author of the record)
  - editor (=the last author of the record)

== Methods ==

Denial of access:

  - a method '''shn_unauthorized()''' realizes error notification and redirection as appropriate
  - non-interactive modes:
    - raise a HTTP error and a JSON error message
    - DO NOT REDIRECT!
  - interactive modes, one of:
    - redirect (e.g. to login) and and display an error message on the target page (acceptable)
    - raise a HTTP error and display an error page, provide redirection options from the error page (more RESTful)
  - shn_unauthorized() takes an optional error message as argument

Module/Controller access:

  - access can be restricted inside the controllers using:
    - '''shn_has_role(role_name)''' which refers to the current user
  - shn_has_role() tests can be combined by '''and''', '''or''' and '''not'''

Table/Record access:

  - table/record access can be restricted by:
    - '''shn_permit(table, method, role, id=None)''' adds role to the list of permitted roles for method on table/record
    - '''shn_deny(table, method, role, id=None)''' removes role from the list of permitted roles for method on table/record
    - '''shn_restrict(table, method, role, id=None)''' replaces the list of permitted roles for method on table/record with [role]
  - table/record access permission is tested by:
    - '''shn_has_permission(table, method, id=None)''', which returns True/False refering to the current user

  - record restrictions override table permissions
  - table restrictions override record permissions