more doc fixes

simplified the security API, and bumped those changes around
a couple more TODO items so I don't forget

Author: Richard Jones

CHANGES.txt

@@ -37,6 +37,8 @@ Feature:
 - unless in debug mode, keep a single persistent connection through a
   single web or mailgw request.
 - HTTP Basic Authentication (sf patch 1067690)
+- extended security.addPermissionToRole to allow skipping the separate
+  getPermission call
 
 Fixed:
 - postgres backend open doesn't hide corruption in schema (sf bug 956375)
@@ -49,6 +51,7 @@ Fixed:
 Fixed:
 - reset ID counters if the database is cleared (thanks William)
 - apply IE caching "fix" to automatically serve up all pages expired
+- fix typo (sf patch 1076629)
 
 
 2004-10-26 0.7.9

TODO.txt

@@ -4,6 +4,11 @@ Required:
 - Security review:
   - write up security model used in classic tracker
   - ensure classic template actually implements the model detailed
+- "Web Access" revocation needs work - the context should not be rendered
+- should redefinitions of a permission keyed off (name, classname) generate
+  an error or a warning? Something needs to be generated, as such
+  occurrances are an error in the schema...
+- check that the Provisional User example actually works as advertised
 
 Optionally:
 - clean up roundup.cgi (switch to config file, use proper logging, remove

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.160 $
+:Version: $Revision: 1.161 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -1133,18 +1133,14 @@ web actions`_).
 
 Each action class also has a ``*permission*`` method which determines whether
 the action is permissible given the current user. The base permission checks
-are:
-
-XXX REVIEW for Permissions changes
+for each action are:
 
 **login**
- Determine whether the user has permission to log in. Base behaviour is
- to check the user has "Web Access".
+ Determine whether the user has the "Web Access" Permission.
 **logout**
  No permission checks are made.
 **register**
- Determine whether the user has permission to register. Base behaviour
- is to check the user has the "Web Registration" Permission.
+ Determine whether the user has the "Web Registration" Permission.
 **edit**
  Determine whether the user has permission to edit this item. If we're
  editing the "user" class, users are allowed to edit their own details -
@@ -1155,11 +1151,9 @@ XXX REVIEW for Permissions changes
  additional property checks are made. Additionally, new user items may
  be created if the user has the "Web Registration" Permission.
 **editCSV**
- Determine whether the user has permission to edit this class. Base
- behaviour is to check whether the user may edit this class.
+ Determine whether the user has permission to edit this class.
 **search**
- Determine whether the user has permission to search this class. Base
- behaviour is to check whether the user may view this class.
+ Determine whether the user has permission to view this class.
 
 
 Special form variables
@@ -1764,7 +1758,12 @@ history         render the journal of the current item as HTML
 renderQueryForm specific to the "query" class - render the search form
                 for the query
 hasPermission   specific to the "user" class - determine whether the
-                user has a Permission
+                user has a Permission. The signature is::
+
+                    hasPermission(self, permission, [classname=],
+                        [property=], [itemid=])
+
+                where the classname defaults to the current context.
 is_edit_ok      is the user allowed to Edit the current item?
 is_view_ok      is the user allowed to View the current item?
 is_retired      is the item retired?
@@ -2674,9 +2673,9 @@ them to various roles. Simply add the new "category" to both lists::
     # to regular users now
     for cl in 'issue', 'file', 'msg', 'category':
         p = db.security.getPermission('View', cl)
-        db.security.addPermissionToRole('User', p)
-        p = db.security.getPermission('Edit', cl)
-        db.security.addPermissionToRole('User', p)
+        db.security.addPermissionToRole('User', 'View', cl)
+        db.security.addPermissionToRole('User', 'Edit', cl)
+        db.security.addPermissionToRole('User', 'Create', cl)
 
 These lines assign the View and Edit Permissions to the "User" role, so
 that normal users can view and edit "category" objects.
@@ -3115,10 +3114,9 @@ Optionally, you might want to restrict the users able to access this new
 class to just the users with a new "SysAdmin" Role. To do this, we add
 some security declarations::
 
-    p = db.security.getPermission('View', 'support')
-    db.security.addPermissionToRole('SysAdmin', p)
-    p = db.security.getPermission('Edit', 'support')
-    db.security.addPermissionToRole('SysAdmin', p)
+    db.security.addPermissionToRole('SysAdmin', 'View', 'support')
+    db.security.addPermissionToRole('SysAdmin', 'Create', 'support')
+    db.security.addPermissionToRole('SysAdmin', 'Edit', 'support')
 
 You would then (as an "admin" user) edit the details of the appropriate
 users, and add "SysAdmin" to their Roles list.
@@ -3908,21 +3906,31 @@ First up, we create the new Role and Permission structure in
     # New users not approved by the admin
     db.security.addRole(name='Provisional User',
         description='New user registered via web or email')
-    p = db.security.addPermission(name='Edit Own', klass='issue',
-        description='Can only edit own issues')
-    db.security.addPermissionToRole('Provisional User', p)
 
-    # Assign the access and edit Permissions for issue to new users now
-    p = db.security.getPermission('View', 'issue')
+    # These users need to be able to view and create issues but only edit
+    # and view their own
+    db.security.addPermissionToRole('Provisional User', 'Create', 'issue')
+    def own_issue(db, userid, itemid):
+        '''Determine whether the userid matches the creator of the issue.'''
+        return userid == db.issue.get(itemid, 'creator')
+    p = db.security.addPermission(name='Edit Own Issues', klass='issue',
+        code=own_issue, description='Can only edit own issues')
     db.security.addPermissionToRole('Provisional User', p)
-    p = db.security.getPermission('Edit', 'issue')
+    p = db.security.addPermission(name='View Own Issues', klass='issue',
+        code=own_issue, description='Can only view own issues')
     db.security.addPermissionToRole('Provisional User', p)
 
+    # Assign the Permissions for issue-related classes
+    for cl in 'file', 'msg', 'query', 'keyword':
+        db.security.addPermissionToRole('User', 'View', cl)
+        db.security.addPermissionToRole('User', 'Edit', cl)
+        db.security.addPermissionToRole('User', 'Create', cl)
+    for cl in 'priority', 'status':
+        db.security.addPermissionToRole('User', 'View', cl)
+
     # and give the new users access to the web and email interface
-    p = db.security.getPermission('Web Access')
-    db.security.addPermissionToRole('Provisional User', p)
-    p = db.security.getPermission('Email Access')
-    db.security.addPermissionToRole('Provisional User', p)
+    db.security.addPermissionToRole('Provisional User', 'Web Access')
+    db.security.addPermissionToRole('Provisional User', 'Email Access')
 
 
 Then in the ``config.ini`` we change the Role assigned to newly-registered
@@ -3933,23 +3941,6 @@ users, replacing the existing ``'User'`` values::
     new_web_user_roles = 'Provisional User'
     new_email_user_roles = 'Provisional User'
 
-Finally we add a new *auditor* to the ``detectors`` directory called
-``provisional_user_auditor.py``::
-
- def audit_provisionaluser(db, cl, nodeid, newvalues):
-     ''' New users are only allowed to modify their own issues.
-     '''
-     if (db.getuid() != cl.get(nodeid, 'creator')
-         and db.security.hasPermission('Edit Own', db.getuid(), cl.classname)):
-         raise ValueError, ('You are only allowed to edit your own %s'
-                            % cl.classname)
-
- def init(db):
-     # fire before changes are made
-     db.issue.audit('set', audit_provisionaluser)
-     db.issue.audit('retire', audit_provisionaluser)
-     db.issue.audit('restore', audit_provisionaluser)
-
 Note that some older trackers might also want to change the ``page.html``
 template as follows::
 
@@ -4200,7 +4191,6 @@ Setting up a "wizard" (or "druid") for controlled adding of issues
    you're done (the standard context/submit method can do this for you).
 
 
-
 -------------------
 
 Back to `Table of Contents`_

doc/installation.txt

@@ -114,8 +114,7 @@ at so you may start playing. Three users will be set up:
 Installation
 ============
 
-Set aside 15-30 minutes. Please make sure you're using a supported version of
-Python -- see `testing your python`_. There's several steps to follow in your
+Set aside 15-30 minutes. There's several steps to follow in your
 installation:
 
 1. `basic installation steps`_ if Roundup is not installed on your system

roundup/cgi/templating.py

@@ -1023,7 +1023,8 @@ class _HTMLUser(_HTMLItem):
     '''Add ability to check for permissions on users.
     '''
     _marker = []
-    def hasPermission(self, permission, classname=_marker):
+    def hasPermission(self, permission, classname=_marker,
+            property=None, itemid=None):
         '''Determine if the user has the Permission.
 
         The class being tested defaults to the template's class, but may

roundup/security.py

@@ -195,11 +195,18 @@ def addRole(self, **propspec):
         self.role[role.name] = role
         return role
 
-    def addPermissionToRole(self, rolename, permission):
+    def addPermissionToRole(self, rolename, permission, classname=None):
         ''' Add the permission to the role's permission list.
 
             'rolename' is the name of the role to add the permission to.
+
+            'permission' is either a Permission *or* a permission name
+            accompanied by 'classname' (thus in the second case a Permission 
+            is obtained by passing 'permission' and 'classname' to
+            self.getPermission)
         '''
+        if not isinstance(permission, Permission):
+            permission = self.getPermission(permission, classname)
         role = self.role[rolename.lower()]
         role.permissions.append(permission)
 

templates/classic/schema.py

@@ -85,38 +85,31 @@
 # REGULAR USERS
 #
 # Give the regular users access to the web and email interface
-p = db.security.getPermission('Web Access')
-db.security.addPermissionToRole('User', p)
-p = db.security.getPermission('Email Access')
-db.security.addPermissionToRole('User', p)
+db.security.addPermissionToRole('User', 'Web Access')
+db.security.addPermissionToRole('User', 'Email Access')
 
 # Assign the access and edit Permissions for issue, file and message
 # to regular users now
 for cl in 'issue', 'file', 'msg', 'query', 'keyword':
-    p = db.security.getPermission('View', cl)
-    db.security.addPermissionToRole('User', p)
-    p = db.security.getPermission('Edit', cl)
-    db.security.addPermissionToRole('User', p)
-    p = db.security.getPermission('Create', cl)
-    db.security.addPermissionToRole('User', p)
+    db.security.addPermissionToRole('User', 'View', cl)
+    db.security.addPermissionToRole('User', 'Edit', cl)
+    db.security.addPermissionToRole('User', 'Create', cl)
 for cl in 'priority', 'status':
-    p = db.security.getPermission('View', cl)
-    db.security.addPermissionToRole('User', p)
+    db.security.addPermissionToRole('User', 'View', cl)
 
 # May users view other user information? Comment these lines out
 # if you don't want them to
-p = db.security.getPermission('View', 'user')
-db.security.addPermissionToRole('User', p)
+db.security.addPermissionToRole('User', 'View', 'user')
 
-# Users should be able to edit their own details. Note that this
-# permission is limited to only the situation where the Viewed or
-# Edited item is their own.
+# Users should be able to edit their own details -- this permission is
+# limited to only the situation where the Viewed or Edited item is their own.
 def own_record(db, userid, itemid):
     '''Determine whether the userid matches the item being accessed.'''
     return userid == itemid
-p = db.security.addPermission(name='View', klass='user', check=own_record,
+p = db.security.addPermission(name='View Self', klass='user', check=own_record,
     description="User is allowed to view their own user details")
-p = db.security.addPermission(name='Edit', klass='user', check=own_record,
+db.security.addPermissionToRole('User', p)
+p = db.security.addPermission(name='Edit Self', klass='user', check=own_record,
     description="User is allowed to edit their own user details")
 db.security.addPermissionToRole('User', p)
 
@@ -126,35 +119,29 @@ def own_record(db, userid, itemid):
 # Let anonymous users access the web interface. Note that almost all
 # trackers will need this Permission. The only situation where it's not
 # required is in a tracker that uses an HTTP Basic Authenticated front-end.
-p = db.security.getPermission('Web Access')
-db.security.addPermissionToRole('Anonymous', p)
+db.security.addPermissionToRole('Anonymous', 'Web Access')
 
 # Let anonymous users access the email interface (note that this implies
 # that they will be registered automatically, hence they will need the
 # "Create" user Permission below)
-p = db.security.getPermission('Email Access')
-db.security.addPermissionToRole('Anonymous', p)
+db.security.addPermissionToRole('Anonymous', 'Email Access')
 
 # Assign the appropriate permissions to the anonymous user's Anonymous
 # Role. Choices here are:
 # - Allow anonymous users to register
-p = db.security.getPermission('Create', 'user')
-db.security.addPermissionToRole('Anonymous', p)
+db.security.addPermissionToRole('Anonymous', 'Create', 'user')
 
 # Allow anonymous users access to view issues (and the related, linked
 # information)
 for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status':
-    p = db.security.getPermission('View', cl)
-    db.security.addPermissionToRole('Anonymous', p)
+    db.security.addPermissionToRole('Anonymous', 'View', cl)
 
 # [OPTIONAL]
 # Allow anonymous users access to create or edit "issue" items (and the
 # related file and message items)
 #for cl in 'issue', 'file', 'msg':
-#   p = db.security.getPermission('Create', cl)
-#   db.security.addPermissionToRole('Anonymous', p)
-#   p = db.security.getPermission('Edit', cl)
-#   db.security.addPermissionToRole('Anonymous', p)
+#   db.security.addPermissionToRole('Anonymous', 'Create', cl)
+#   db.security.addPermissionToRole('Anonymous', 'Edit', cl)
 
 
 # vim: set filetype=python sts=4 sw=4 et si :

templates/minimal/schema.py

@@ -25,25 +25,22 @@
 # REGULAR USERS
 #
 # Give the regular users access to the web and email interface
-p = db.security.getPermission('Web Access')
-db.security.addPermissionToRole('User', p)
-p = db.security.getPermission('Email Access')
-db.security.addPermissionToRole('User', p)
+db.security.addPermissionToRole('User', 'Web Access')
+db.security.addPermissionToRole('User', 'Email Access')
 
 # May users view other user information?
 # Comment these lines out if you don't want them to
-p = db.security.getPermission('View', 'user')
-db.security.addPermissionToRole('User', p)
+db.security.addPermissionToRole('User', 'View', 'user')
 
-# Users should be able to edit their own details.
-# Note that this permission is limited to only the situation
-# where the Viewed or Edited item is their own.
+# Users should be able to edit their own details -- this permission is
+# limited to only the situation where the Viewed or Edited item is their own.
 def own_record(db, userid, itemid):
     '''Determine whether the userid matches the item being accessed.'''
     return userid == itemid
-p = db.security.addPermission(name='View', klass='user', check=own_record,
+p = db.security.addPermission(name='View Self', klass='user', check=own_record,
     description="User is allowed to view their own user details")
-p = db.security.addPermission(name='Edit', klass='user', check=own_record,
+db.security.addPermissionToRole('User', p)
+p = db.security.addPermission(name='Edit Self', klass='user', check=own_record,
     description="User is allowed to edit their own user details")
 db.security.addPermissionToRole('User', p)
 
@@ -53,19 +50,16 @@ def own_record(db, userid, itemid):
 # Let anonymous users access the web interface. Note that almost all
 # trackers will need this Permission. The only situation where it's not
 # required is in a tracker that uses an HTTP Basic Authenticated front-end.
-p = db.security.getPermission('Web Access')
-db.security.addPermissionToRole('Anonymous', p)
+db.security.addPermissionToRole('Anonymous', 'Web Access')
 
 # Let anonymous users access the email interface (note that this implies
 # that they will be registered automatically, hence they will need the
 # "Create" user Permission below)
-p = db.security.getPermission('Email Access')
-db.security.addPermissionToRole('Anonymous', p)
+db.security.addPermissionToRole('Anonymous', 'Email Access')
 
 # Assign the appropriate permissions to the anonymous user's
 # Anonymous Role. Choices here are:
 # - Allow anonymous users to register
-p = db.security.getPermission('Create', 'user')
-db.security.addPermissionToRole('Anonymous', p)
+db.security.addPermissionToRole('Anonymous', 'Create', 'user')
 
 # vim: set et sts=4 sw=4 :