--- a/doc/security.txt	Sun Jul 14 23:18:20 2002 +0000
+++ b/doc/security.txt	Mon Jul 15 02:04:57 2002 +0000
@@ -2,7 +2,7 @@
 Security Mechanisms
 ===================
 
-:Version: $Revision: 1.6 $
+:Version: $Revision: 1.7 $
 
 Current situation
 =================
@@ -110,15 +110,17 @@
 
 In practice, this is implemented as:
 
-1. there's a mapping of user -> role          (in hyperdb)
-2. there's a mapping of role -> permission    (in code)
-3. there's a function that's available to all roundup code that can ask
+1. there's a mapping of user -> role                (in hyperdb)
+2. there's a mapping of role -> permission          (in code)
+3. there's a set of permissions defined, possibly set against a specific class
+   (in code)
+4. there's a function that's available to all roundup code that can ask
    whether a particular user has a particular permission.
 
 Pros:
 
    - quite obvious what is going on
-   - is the current system
+   - is very similar to the current system
 
 Cons:
 
@@ -135,8 +137,8 @@
 Role, which encompasses several Permissions and may be assigned to many Users,
 is quite well developed in many projects. Roundup will take this path, and
 allow the multiple assignment of Roles to Users, and multiple Permissions to
-Roles. These definitions will be stored in the hyperdb.
-
+Roles. These definitions will be stored in the hyperdb. They don't need to be
+pushed to the actual database though.
 
 A permission module defines::
 
@@ -160,8 +162,13 @@
 
     class PermissionClass(InMemoryImmutableClass):
         ''' Include the default attributes:
-            - name (String, key)
+            - name (String)
+            - classname (String)
             - description (String)
+
+            The classname may be unset, indicating that this permission is not
+            locked to a particular class. That means there may be multiple
+            Permissions for the same name for different classes.
         '''
 
     class RoleClass(InMemoryImmutableClass):
@@ -171,37 +178,46 @@
             - permissions (PermissionClass Multilink)
         '''
 
-    def hasPermission(db, userid, permission):
+    def hasPermission(db, userid, permission, classname):
         ''' Look through all the Roles, and hence Permissions, and see if
-            "permission" is there
+            "permission" is there for the specified classname.
         '''
 
-
-The instance dbinit module then has::
-
-  in open():
+The instance dbinit module then has in ``open()``::
 
     perm = permission.PermissionClass(db, "permission")
     role = permission.RoleClass(db, "role")
 
+    # create some Permissions
     wa = perm.create(name="Web Access",
-                    description="User may log in through the web")
+                    description="User may use the web interface")
     wr = perm.create(name="Web Registration",
                     description="User may register through the web")
+
     ma = perm.create(name="Mail Access",
-                    description="User may log in through email")
+                    description="User may use the email interface")
     mr = perm.create(name="Mail Registration",
                     description="User may register through email")
-    ae = perm.create(name="Access Everything",
-                    description="User may access everthing")
+
+    ee = perm.create(name="Edit",
+                    description="User may edit everthing")
+    ei = perm.create(name="Edit", classname="issue",
+                    description="User is allowed to edit issues")
+
+    ae = perm.create(name="Assign",
+                    description="User may be assigned to anything")
+    ai = perm.create(name="Assign", classname="issue",
+                    description="User may be assigned to issues")
+
+    # create some Roles that use the Permissions
     role.create(name="User", description="A regular user, no privs",
-                permissions=[wa, wr, ma, mr])
+                permissions=[wa, wr, ma, mr, ei, ai])
     role.create(name="Admin", description="An admin user, full privs",
-                permissions=[ae])
+                permissions=[ee, ae])
     role.create(name="No Rego", description="A user who can't register",
                 permissions=[wa, ma])
 
-  in init():
+in ``init()``::
 
     r = db.getclass('role').lookup('Admin')
     user.create(username="admin", password=Password(adminpw),