so, i’m sure you’ve had that problem. no, not that one, the one where you want to store a bunch of things that are similar, but not identical, in the same database table. for instance, you want to store files uploaded to your site in an “uploads” table. since you are a normalization freak like myself, you put the common fields in the “uploads” table, then happily start to make helper/lookup tables that will contain the “weird” fields. so, when you look up a particular upload record, you can easily select (or LEFT JOIN) all the “weird” fields associated with that particular record. works great. but then, you perhaps want to do this for another table. rinse, repeat. since you are exactly like me, you probably thought to yourself “well, time to make a polymorphic table to contain all this mess”. so, you create One Table To Rule Them All, with model/foreign_id fields, and all is well. until you, like me, decide that you want hierarchical data. “no problem” you think, “that’s why God (or the Devil, if you ask most programmers) invented tree structures!”. so you update your OTTRTA (see above for witty acronym) table to actAs Tree. fine, works great. until you get millions of rows and something goes corrupt (it always does, trust me).

what now?

well, since it is my mission in life to suffer so that you don’t, i have experienced all of the above and more so that i could present to you:

THE METADATA PLUGIN (for CakePHP 1.3+)

wtf does it do, i hear you asking? good thing i made a github project page, because it tells me the metadata plugin is “A CakePHP 1.3 plugin that provides arbitrary metadata storage for model records”.

simple enough.  so, how to set it up:

1. check out the code from github:

   $ cd /path/to/your/app/plugins && git clone git://github.com/jmcneese/metadata.git

   if you already have your project under git you can do this (it’s call sub-tree’ing), or muddle through setting up and using submodules. pick your poison.

2. create the required db table. you can either do this via the SQL files included in metadata/config/schema (there are two, those who prefer UUID ids, and those who prefer INT), or you can use the schema shell to do this:

   $ cake schema create Metadata.metadata

3. set metadata as a behavior on the models you wish to use it with, ala:

   var $actsAs = array('Metadata.Metadata' => array(
       'validate' => array(
           'fieldName' => array(
               'rule'      => 'postal',
               'message'   => 'Must be valid postal code',
           ),
           'some' => array(
               'nested' => array(
                   'array' => array(
                       array(
                           'rule'      => 'numeric',
                           'message'   => 'Must be numeric'
                       ),
                       array(
                           'rule'      => array(
                               'decimal',
                               2
                           ),
                           'message'   => 'Must be decimal'
                       )
                   )
               )
           )
       )
   ));
   

4. Define any validation rules that you need, in a similar fashion to model validation rules (all the built-in Validator rules work). Multiple rules per node are supported, and nodes can be as deep as required.

so, #1 and #2 are pretty cut and dry, but #3 and #4 probably merit more explanation:

you can specify whatever nodes you want validated, so long as they are “leaf” nodes.  a leaf node is one that does not have children underneath it.  take the following example:

$some_metadata = array(
    'settings' => array(
        'profile' => array(
            'show_gravatar' => true,
            'hide_email' => false
        ),
        'anonymous' => false
    )
);

the nodes ‘settings.anonymous’, ‘settings.profile.hide_email’ and  ’settings.profile.show_gravatar’ would be “leaf” nodes, in that they have no children.  ’settings.profile’ would not be a leaf, and thus cannot have validation rules associated with it (can’t really think of any you would need/want anyhow).

all the rules that are built in to the core Validation class are supported.  unlike model validation, you cannot (currently) specify your own custom rules, as this still needs to be built out.

multiple rules per node are supported, so long as you format them as shown above.

the ‘last’ parameter is supported for validation rules, but that’s it (no “on” or any other model validation parameter).

how to shake your meta-thing

first off, you can use the methods getMeta() and setMeta().  for this to work, the model must be referencing a valid model record, ala:

$this->Stuff->id = 1; // or whatever you use for primary key ids
$this->Stuff->setMeta('foo','bar');

now, the metadata “foo” with the value of “bar” is set for the record with the id of the record for the model “Stuff”.  now, to retrieve the metadata:

$this->Stuff->id = 1; // or whatever you use for primary key ids
$meta_foo = $this->Stuff->getMeta('foo');
// $meta_foo now equals 'bar'

much like the Configure class, you can set n-level deep keys:

$this->Stuff->id = 1; // or whatever you use for primary key ids
$this->Stuff->setMeta('some.deeply.nested.setting','shoop');

doing this creates a nested structure that holds all these keys, and allows you to query as deep as you wish:

$this->Stuff->id = 1; // or whatever you use for primary key ids

$meta = $this->Stuff->getMeta('some.deeply');
// this results in:
$meta = array(
    'nested' => array(
        'setting' => 'shoop'
    )
);

if you pass no path to getMeta, it will return all metadata associated with the model record in question. alternately, you can pass an entire array to setMeta() and the entire structure will be saved. pre-existing keys will be merged with what you pass.

another way to save metadata (particularly when creating a new record) would be to include it in the data you pass to your primary model when saving. to illustrate:

$this->Stuff->create();
$this->Stuff->save(array(
    'Stuff' => array(
        'name' => 'blah',
        'Metadatum' => array(
            'settings' => array(
                'show' => false
            )
        )
    )
));

this would cause the new Stuff record to be created, and the metadata saved along with it. after that saved, you’d be able to:

$show_stuff = $this->Stuff->getMeta('settings.show');

don’t look behind the curtain

this all works by utilizing the TreeBehavior, specifically with the scoping configurations that limit the tree calculations to just a small section of the overall table.  this means that you may have hundreds of thousands of (or millions even) trees in your metadatum table with no noticeable degradation in performance (other than the natural one that happens when your tables get large).  it’s conceivable that any of these mini-trees could become corrupt, and for that there are some custom methods for dealing with this, verifyMeta() and recoverMeta().  these work pretty much exactly like the TreeBehavior methods verify() and recover(), except that they set the scope of the tree first.

also, if you are feeling particularly brave, you can use the Metadatum model directly via setKey()/getKey() (both of these work just like get/setMeta(), except they don’t scope the internal tree).  this can be useful for application-wide settings/metadata, but i would really recommend using Configure for that.

now, go fork it and fork it well!

as always:

caveat emptor

this works for my purposes as it stands, but i imagine that there may be those out there who would like it to exactly mimic model validaton (what with the “on” parameter, or custom validation).  as with other projects, i accept bug reports, suggestions, donations, patches and/or feature requests.

future plans

one of the biggest things that still needs to be implemented is the auto-inclusion of metadata when finding primary model records.  as it stands now, you have to retrieve any and all metadata via the getMeta() method, they are never automatically included, as when a model hasAndBelongsToMany some other model.  this is because the Metadatum model is not bound/associated in any way to the primary model.  i’ll look into finding some way to configure this sort of behavior.

…and the Permissionable plugin rose from the ashes…

with apologies to the queen

after an incredibly long delay i have updated the PermissionableBehavior to be a more feature complete plugin (1.3 compatible). my apologies for taking so long, life has been hectic.  if you don’t know what i’m talking about, go look here and come back.

so, where’s the beef?

what does the update contain, you ask? well, that’s an excellent question!

• all code bundled up in a nice tidy plugin
• the concept of group bits has been discarded, removing the artificial limitation on number of possible groups
• much faster (possibly due to cakephp 1.3 being faster, dunno)
• test cases and fixtures (100% coverage, bitches!)
• using constants for user_id/group_id(s) has been abandoned in favor of static storage classes (note: not that i think constants are a bad solution, but only that the static class is more flexible)
• behavior init now binds the Permissionable.Permission model in a hasOne association to the primary model.  this is better than the previous adding of a join via the $queryData in beforeFind
  • an additional benefit of this is the unbinding of the model when permissions are not needed (when user is root, or when permissions have been disabled)
• more concise handling of permissions checking
• better handling of “backout” scenarios (when a record is attempted to be saved when no permissionable information is available)
• better handling of model aliasing, which should help prevent name collisions when querying multiple models that reference the same permissioned model
• added cake schema file to easily create the permissions table (along with a couple SQL files, for those afraid of the command-line)
• 500% cooler. it’ll bring all the boys to the yard.
• Permissionable now lives on github.  it’s enjoying its stay so far.  go check it out.

how do i tame this wild beast?

easier than ever:

1. check out the code from github:

   cd /path/to/your/app/plugins && git clone git://github.com/jmcneese/permissionable.git

   if you already have your project under git you can do this (it’s call sub-tree’ing), or muddle through setting up and using submodules.  pick your poison.

2. create the required db table. you can either do this via the SQL files included in permissionable/config/schema (there are two, those who prefer UUID ids, and those who prefer INT), or you can use the schema shell to do this:

   cake schema create Permissionable.permission

3. take a look at permissionable/controllers/components/permissionable.php. you’ll need to include this in the components array for whichever controllers use your permissioned models, or in AppController.

   public $components = array('Permissionable.Permissionable');

   also, you’ll need to put some code in the initialize method of the component that sets the id of the logged in user (via AuthComponent or whatever method you use), as well as the group id(s).

4. next up, you’ll need to include the behavior in whatever models you want to be permission-controlled:

   public $actsAs = array('Permissionable.Permissionable' => array('defaultBits'=>480);

   note: you need not include the defaultBits option to the behavior, unless you a) know what you are doing, b) can calculate up the proper bits and c) really need to. if any of the above apply, feel free.  if you need a refresher course, look here.

*batteries not included

so, now that you’ve done all that, there’s only a few things you need to know about how to use it.  as before, permissions are checked on the fly and transparently.  if you have permission to the action you are trying to perform (read/update/delete), then your model call will be successful.  if not, you’ll get a big fat false.  if you wish to disable this on a per-find basis, you can. e.g.:

$result = $this->Foo->find('all', array(
    'permissionable' => false,
    'conditions' => array(
        'Foo.val' => 'Bar'
    )
));

or, this way, in case you need to add it to the scope of something like TreeBehavior or AuthComponent:

$result = $this->Foo->find('all', array(
    'conditions' => array(
    'permissionable' => false,
        'Foo.val' => 'Bar'
    )
));

permissions will always be created updated on save though. i might make this configurable in the future, or accept patches for it via github.   you can, however, override the permissions of the item being saved via:

$this->Thing->save(array(
    'Thing' => array(
        'name'	=> 'Baz',
        'desc'	=> 'Baz is a Thing!'
    ),
    'Permissionable' => array(
        'perms' => 416
    )
));

what the future holds

i intend on updating the plugin to have more options for configuration, to whit: implementing some level of inheritable permissions, introducing the concept of roles, supporting “trickle-down” permission changes to models that actAs Tree, common UNIX-y commands like chmod/chown/chgrp.

as always, i welcome comments, questions, patches and suggestions. if you find a bug, let me know… or better yet, submit a patch!

caveat emptor, balatros

• i assume that you have users and groups, meaning that your user has a primary group, and secondary groups.  this is UNIX-like, after all.  now, an easy and standard way to do this is define model associations like User hasMany Group, User belongsTo Group.  it’s really up to you how you want to get that list, Permissionable doesn’t care, so long as you set it in the component.

no, not Rambunctious Models Artfully Concealing Faded Temptress Wrinkles, it’s even better.

those of you who have been following the PermissionableBehavior know that the goal of the behavior is to help achieve a RBAC-like system to control not only access to specific parts of an application, but also row-level permissions on data in the application.  i released an initial prototype of the behavior a couple weeks ago, and it was fairly well-received.

i’ve refactored a little bit, and per popular demand, i’ll also be supplying a sample implementation for those of you who prefer learning by example.  first though, i thought i would take a step back and try to outline the overall design and how it works.

a shave and a haircut, 9 bits

bit(mask)s are a wonderful and compact way to keep track of multiple booleans.  i’m not even going to attempt to explain why, since wikipedia can do it so much better. until you get the hang of them they can be a little confusing, but they are really just a different (and far more basic) way of looking at what you are already used to.  let’s look at some examples, in which i’ll limit to be relevant to the PermissionableBehavior.

let’s set the parameters.  the bit definitions for the row action we want to limit are:

• Owner
  • Read – 256
  • Write – 128
  • Delete – 64
• Group
  • Read – 32
  • Write – 16
  • Delete – 8
• Other
  • Read – 4
  • Write – 2
  • Delete – 1

notice that the numbers for the permissions increase in powers of 2.  i’ll not go into why this works, since it’s covered elsewhere, but sufficed to say that bitwise, each number is distinct and non-inclusive of the other numbers (256 does not contain 128, 128 does not contain 64, etc).

ok, now imagine the permissions that we want to assign to an item as a binary number.  trust me, it’s actually easier:

this bitmask indicates that no one has any permission to a record with these bits set (or unset, actually).  now let’s look at a more real-world example:

what’s going on here?  the binary number 110110100 == the decimal number 436 (256+128+32+16+4, according to the numbers i assigned above).  storing the number 436 as the permission bit on a record would reflect that the owner of the record can read/write, the group owner(s) of the record can read/write, and all others (non-owners) can read.  with bitwise operators, it’s trivial to see if a permission bit has required permissions.

for example, let’s use the “&” (AND) bitwise operator to see if the row’s permission bit contains the bit that says that the owner can delete the row (64).

$allowed = ((436 & 64) <> 0);

how does this work?  since (436 & 64) equals 0, then the request for owner to delete would be denied, as the row permission does not contain 64. the ‘&’ operator tests returns which bits are set in both numbers.  as you can see above, there is no column in which both have 1 set, thus returning ’0′.

NOTE:  you must enclose the bitwise operation in parentheses or you will get false positives.  due to the logical order in which the operation is processed, if you tried to do (426 & 64 <> 0), it would return true, since the “not 0″ portion is processed first.  additionally, unless you have a firm grip on your variable types, i recommend typecasting all your variables as integers, e.g. ((int) $x & (int) $y) <> 0), since if either variable is string, then you’ll get bizarre results.

now for an example where the request is allowed:

now, notice that in the Other Read column, both numbers have the bit set. and so (436 & 4) would return ’4′, indicating that both numbers have the ’4′ bit set.

NOTE: there are several ways to test using this operator. i use (x & y) <> 0, when you can also use (x & y) == y. the latter will work in most scenarios, but in the PermissionableBehavior i have some places where permissions are inherited, and so the returned number is sometimes a product of shared bits, meaning it returns neither 0 or the mask. in either case, <> will work.

2 bits walk into a |, and the operator says “2″

so far i’ve been using the permission bits for example, but all the above also applies to the group bits assigned to a row.  this works the same way permissions do, ala:

• Root – 1
• Global – 2
  • Internal – 4
    • Dept. A – 8
    • Dept. B – 16
  • External – 32
    • Client A – 64
    • Client B – 128

now, here is one of the drawbacks of this approach.  you are limited to the number of bits in an integer, whatever your architecture supports.  in the case of 32bit, this equates to 32 groups, and 64bit, 64 groups.  this isn’t a problem for me, and i’m sure there are ways to get around this (hashing, bribery, etc), but i’ll not address this until i actually have a polished version of the behavior (or need more than 32 groups!).

anyway.  as i said, what applied for permission bits works the same for group bits.  let’s assume we have a user who is in Dept. B.  in the PermissionableBehavior, i traverse the groups tree and add up all the bits for the groups that the user is part of.  be careful, since you can’t just add up using arithmetic since any duplication of bits would produce inaccurate results.  the group bits for a user in Dept. B would be 22 (16 | 4 | 2).  note the use of the “|” (OR) operator.  this operator works by returning the bits that are set in both sets of numbers.  since none of the bits in the group path for Dept. B are inclusive (16 does not include 4 or 2, 4 does not contain 2), the result is the the bits added up and we get 22.  but what if the user was in multiple groups?  let’s say the user is in Dept. B and Client A groups.  if we iterated each group and added up it’s path, we’d get 120.  this would be wrong, as it includes the ‘Global’ bit (2) twice, thus skewing the resulting bits.  the right way would be to use bitwise OR, like so (64 | 32 | 2 | 16 | 4 | 2), which gives us a group bits of 118.  Now for the real-world example:

if a row in the database has a group bits of 96, we can test whether or not someone has access to the group owner permissions by comparing their cumulative group bits with the rows.

$is_group_owner = ((96 & 118) <> 0);

since (96 & 118) returns ’96′, that being the bits that are shared by both numbers, we know that the user in question has access to the group permissions, in that he is in at least one group that the row is also in.

group bits + permission bits == unix delicious

so, now that we’ve covered how the group and permission bits work, i’ll show how these method actually limit the results from a database query, so that a user is only able to perform allowed actions.

first off, let’s go for the simple case: selecting rows from a table.  let’s set the parameters first.  User A is in the groups Dept. A and Client B.  her ID in the users table is 100 (for example), and her group bits are 118.  she performs a query via $groupModel->find(‘all’).  without the Permissionable behavior, the query would look something like this:

SELECT `Group`.*
  FROM `groups` AS `Group`

with the PermissionableBehavior however, the same $groupModel->find(‘all’) would result in this query (and i apologize again for not having syntax formatting/highlighting… does anyone recommend a free webhost?):

SELECT `Group`.*, `PermissionModel`.*
  FROM `groups` AS `Group`
  INNER JOIN permissions AS `PermissionModel` ON (
    `PermissionModel`.`model` = 'Group'  AND -- since the PermissionModel is polymorphic, we need to limit to rows that have to do with the primary model
    `PermissionModel`.`foreign_key` = `Group`.`id` AND
    (
      (`PermissionModel`.`permission` & 4 <> 0) OR  -- first check for 'other read' permission
        (
          (`PermissionModel`.`permission` & 32 <> 0) AND -- otherwise 'group read'
          (`PermissionModel`.`group_bits` & 118 <> 0) -- assuming the user and the row share a group
        ) OR (
          (`PermissionModel`.`permission` & 256 <> 0)  AND -- otherwise 'owner read'
          (`PermissionModel`.`user_id` = '100') -- assuming the user is the row owner
        )
      )
    )

now, i’m sure several of you are looking at that and thinking “bleeding jesus h. christ on a pogostick, that’s a lot of parentheses”, but they are necessary and not really all that complex.  i should blog about the queries i had to write for a database that had +1 billion rows… but i digress; the query, while more than twice as “long” as the previous, really doesn’t incur any overhead, especially when your tables are properly indexed. what’s nice about this approach is that the original query was modified to filter out rows in the primary table that do not have the appropriate permissions. in this case we’ve specified “read” permissions (owner – 256, group – 32, other – 4) as our criteria. we’ve only applied the owner read permission condition if the user is indeed the owner, and the group permission only if the row and the user share at least one group, or if the row has an ‘other read’ bit set.  on my modest macbook pro, this takes less than a millisecond to query, and EXPLAIN tells me that the query is using only simple selects, constant and indexed references with only a WHERE for the inner join.

stop teaching me how to fish, just give me a fish dammit

alright, as promised, here’s the example application that you can just unarchive (over a fresh cake install) and play with: ZOMG Download ME!!!!1

a couple things i didn’t explain before, but bear mentioning:

• the order in which you add the behavior to your models (most notably  Tree’d models) is very important.  i’d recommend putting Permissionable first, in most cases.
• if you don’t use AuthComponent to authenticate your users, you’ll need to make sure that any query that it does on a permissioned model includes ‘permissions’ => false in it’s conditions
• oh yeah, you can disable the behavior runtime by either:
  • including ‘permissions’ => false in your query conditions.
  • calling $model->disableChecks() to disable just permission checking.
  • calling $model->disableCreation() to disable, you guessed it, permission creation.
  • or by calling $model->disable() to shut the whole thing down.
  • to enable again, just call $model->disable(false), or write a method called ‘enable’.  i dare you.
• you can add considerably more permissionable actions, so long as you keep incrementing the bits by the power of two.  please only do so if you understand what you are doing, since you’ll have to shift the permission bits around (at least i would, so they would remain pretty), and most likely re-test the whole thing since i didn’t really code with that in mind. although it should work.
• i make no claims about this being perfect.  i haven’t tested in with all other core behaviors, and there still may be weirdness that may crop up.  YMMV, caveat emptor, amen.

<insert witty closing heading here>

so there you have it, folks.  as always, i welcome comments, questions, critique, praise, beer and naked pictures (ladies only please).  anyone who has suggestions on how to improve this code, please do so.  i am committed to making this the first step in a much larger plugin that can theoretically replace cake default ACLs.

speaking of which, stay tuned for the second part of this article, entitled “RBAC FTW (part 2)”, in which we will see how we still need the cake ACL structure to limit access to controller actions, thus rounding out this first effort towards our stated lofty goal.

and here it is.

so, there apparently is a bit of scuffle about my last post, so let me clear things up.

first off, this is my first real blog, and first real blog post of any substance, so i’m still learning.

secondly, i wasn’t attacking cake, cake devs, or cake ACLs.  all of the above rock the llama’s ass.

thirdly, cake devs have said that using cake ACLs for row-level access/deny is probably not the best way to accomplish what you probably want to do.  nate abele’s opinion as to whether or not any cake dev would say that is irrelevant, as it was said, for better or worse.  i happen to agree with the sentiment, not because cake’s ACL implementation is poor (it’s not), but because using ACLs for row level access is flawed from the get-go.  sure, it can be done, just as an entire application can be built without a framework, or as a monolithic index.php with a shit-ton of functions. it is just not good separation of concerns, and i didn’t see that until after i had tried three different ways to limit access to specific rows in a database using ACLs. i reiterate the quote from mark story that if you use cake ACLs to limit row access you “have to know the answer to the question before you even ask it”.

what did mark mean by this?  he meant that if you have even a simple setup with users being in groups (and groups not being hierarchical), you must query the model in question joining in various ACL models to find allowed ids before you can even ask the original model for rows that match those ids.  when you deal with inherited permissions from a group model that is tree-based, you have even more complexity.  i.e. for the group that the user is in, you have to iterate upwards in the tree to see if that particular group has access to the row in question.  and if your requirements call for your users to be in multiple groups (which cake default ACL behavior/component doesn’t support at all), then it’s even more complex, since you have to loop through the ancestor tree of every group that the user is in.  and to top it all off, if the model you are trying to read is also a tree, you not only have to do all of the above, but you also solve the problem of denied parent nodes, and figure out how to deal with non-explicitly denied children of denied parent nodes.  it’s a mess.  i had a completely working implementation of what i just described and when i issued a single Model::read() on a record owned by a user who was in three groups, it performed fourteen queries to determine if you user could see he his own record!  did it work?  sure.  was it optimal? fuck no.  would indexing help me? sure, until my tree got huge, and i would never be able to shake the feeling that i was doing things the wrong way just to stick to purely cake components.

fourthly, i am not advocating or urging the use of either ACLs or UNIX-y permissions.  both are good when used appropriately.  both can be overkill for simple “can user x do y” scenarios.  it’s merely what worked for me, and i want to share.  in fact, what is missing from my previous article is noting that to achieve a “real” RBAC permissioning system, both row-level access like this and ACLs are required (at least in cake terms).  ACLs to know who can access what part of the system, and a simple method like mine to determine who can change what in the data.  if someone can address my concerns noted above as to how this can be done in a generic implementation of ACL like cake’s, and it does not require a whole handful of queries before the actual model query requested (note: a simple find(‘all’) with the Permissionable behavior doesn’t increase the query count at all), then i’ll eat crow.

Core Developer says “You Don’t Need It”

it seems that for as long as i have been using cake, i’ve been hearing people asking “how do i control access to an individual record with ACL?”.  the usual response is “you aren’t doing it right if you need to restrict access to a specific row”.  while this may be correct 90% of the time (due to the php/development greenhorns who use cake, but that’s a different blog post), i think it’s a bit narrowminded to think in this way.  who’s to say whether or not i or my product owner want to restrict access to certain db rows?  and how much of that response is due to the fact that cake’s generic ACL implemenation makes doing row level permissions a nightmare?  and so, remembering the “good old days” when i used phpGACL in projects, i wondered if there was a better way to do this in cake, that doesn’t require backporting an old clunky library like phpGACL (which i’ve seen done elsewhere).

Enter the “RMAC” dragon

awhile back, i ran across this post on by Baron Schwartz, author of the excellent O’reilly book “High Performance MySQL” and various handy mysql tools.  his two-part article on how to implement role based access in just sql is very intriguing, to say the least.  while i like his implementation, it’s has a lot of bells and whistles that are more specific to his requirements that i would need.

around a year ago, i tasked one of my developers with adapting Baron’s implementation to fit our requirements.  in the end, while it was a good stab at it, i think we still tried to make it do too much, and there were various problems with our implementation (accessing $_SESSION in a model behavior gives me shivers), but it did what we needed it to do and all was good.

for a new project we are working on i thought i would try to do this from scratch.  i’ll leave off describing all the exhaustive implemenation/testing that was done to verify whether or not this can be done with cake’s built in ACL behavior/component.  in a nutshell, the answer is yes, but to put it how Mark Story said “you have to know the answer to the question before you even ask it”, in that you have to query the model in question, along with the aros/acos/aros_acos table to find a list of row ids that you are able to access, and then use that as a filter for your original query.  this becomes even more tedious when dealing with a tree behaviored model, because you will run into the scenario where someone may be allowed to access a node several levels deep in the tree, but disallowed access to it’s parent.  you then have to decide to bypass the permissions and give the user access to read the parent node, or else change the way you save permission for each user/group to implicitly allow paths.  this sucks, to say the least.  after all this “research” (read: unsatisfactory implementations that made my head hurt to try to keep straight), i scrapped all of this.  i have come to the conclusion that cake’s ACL is a very good generic implementation that never was explicitly intended for use with users/groups, much less roles.  that is not to say you can’t, but that you probably shouldn’t.  turns out the cake core developers were right (but i still think that blithely ignoring the fact that it’s just not suited for this sort of implementation is kind of naughty).

so where does this leave us?  after scrapping the implementations that used cake’s generic ACL, i returned to Baron’s method and stripped it down.  while i don’t have it in a “plug-n-play” state just yet, here she is, the Permissionable behavior! </trumpet flourish> (apologies for not having syntax highlighting!)

/**
 * Permission Model
 *
 * Model for manipulating permissions data
 *
 * @author      Joshua McNeese
 */
final class PermissionModel extends AppModel {

    /**
     * Permissions table
     *
     * @access  public
     * @var     string
     */
    public $useTable = 'permissions';

}

/**
 * Permissionable Behavior
 *
 * @author      Joshua McNeese
 * @since       1.0
 * @internal    $Info: $
 * @version     $Rev: $
 */
final class PermissionableBehavior extends ModelBehavior {

    public $settings    = array();
    private $__defaults = array(
        'userModel'     => 'User',
        'groupModel'    => 'Group',
        'defaultBits'   => 416      // owner_read (256) +
                                    // owner_write (128) +
                                    // group_read (32)
    );
    private $__enabled  = true;

    /**
     * Bits for various permissions.  Don't touch!
     *
     * @access  private
     * @var     array
     */
    private $__permissions = array(
        'owner_read'   => 256,
        'owner_write'  => 128,
        'owner_delete' => 64,
        'group_read'   => 32,
        'group_write'  => 16,
        'group_delete' => 8,
        'other_read'   => 4,
        'other_write'  => 2,
        'other_delete' => 1
    );

    public function setup(&$model, $config = array()) {
        $model->Permission =& ClassRegistry::init('PermissionModel');

        $config = (is_array($config) and !empty($config))
                ? am($this->__defaults, $config)
                : $this->__defaults;

        foreach($config as $k=>$v) {
            if(isset($model->{$k})) {
                $config[$k] = $model->{$k};
            }
        }

        $this->settings[$model->alias] = $config;
	}

	public function afterDelete(&$model) {
	    if(!$this->isEnabled()) {
	        return true;
	    }

        $model->Permission->deleteAll(array(
            'model'         => $model->alias,
            'foreign_key'   => $model->id
        ));
	}

	public function afterSave(&$model, $created) {
	    if(!$this->isEnabled()) {
	        return true;
	    }

	    if(
	       !defined('PERMISSION_GROUP_BITS') or
	       !defined('PERMISSION_USER_ID')
        ) {
	        return $this->backout($model);
	    }

	    $data = array();

	    if($created) {
	        $data = array(
                'model'         => $model->alias,
                'foreign_key'   => $model->id,
                'user_id'       => PERMISSION_USER_ID,
                'group_bits'    => PERMISSION_GROUP_BITS,
                'permission'    => $this->getPermissionBits($model)
	        );

	        $groupModelName = $this->settings[$model->alias]['groupModel'];
	        $userModelName  = $this->settings[$model->alias]['userModel'];

	        if($model->alias == $userModelName) {
	            $data['user_id'] = $model->id;

	            if(
	               !isset($model->data[$groupModelName]) or
	               empty($model->data[$groupModelName])
                ) {
                    return $this->backout($model);
                }

                $groupIds = array_unique(am(
                    Set::extract(
                        "/$groupModelName/$groupModelName/.",
                        $model->data
                    ),
                    Set::extract(
                        "/$groupModelName/{$model->{$groupModelName}->primaryKey}",
                        $model->data
                    )
                ));

                if(empty($groupIds)) {
                    return $this->backout($model);
                }

                $groupModel= $this->getModel($model, $groupModelName);

                if(empty($groupModel)) {
                    return $this->backout($model);
                }

                $groupBits = 0;

                foreach($groupIds as $groupId) {
                    $bitPath    = $groupModel->getpath($groupId, array('bit'));
                    $bitArray   = array_sum(Set::extract("/$groupModelName/bit", $bitPath));
                    $groupBits  = (int) $groupBits | (int) $pathBits;
                }

                if(empty($groupBits)) {
                    return $this->backout($model);
                }

                $data['group_bits'] = (int) $groupBits;
	        } elseif($model->alias == $groupModelName) {
	            $data['group_bits'] = $model->data[$groupModelName]['bit'];
	        }

	        $model->Permission->create();
	    } elseif(
	       isset($model->data['Permission']) and
	       !empty($model->data['Permission'])
        ) {
	        $data = $model->data['Permission'];

	        if(!isset($data['id']) or empty($data['id'])) {
	            $oldPermission = $model->Permission->find('first', array(
                    'conditions' => array(
                        'model'         => $model->alias,
                        'foreign_key'   => $model->id
    	            )
	            ));

	            if(empty($oldPermission)) {
	                $model->Permission->create();
	                $data['permission'] = $this->getPermissionBits($model);
	            } else {
	                $data = am($oldPermission['Permission'], $data);
	            }
	        }

	        $data = am($data, array(
	           'model'         => $model->alias,
               'foreign_key'   => $model->id
	        ));
	    }

	    if(!empty($data)) {
	        $model->Permission->save($data);
	    }
	}

	public function beforeDelete(&$model) {
	    if(!$this->isEnabled()) {
	        return true;
	    }

	    return $this->hasPermission($model, 'delete');
	}

	public function beforeFind(&$model, $queryData) {
	    if((
            isset($queryData['permissions']) and
	        $queryData['permissions'] == false
        ) or (
            isset($queryData['conditions']['permissions']) and
            $queryData['conditions']['permissions'] == false
        )) {
	        unset($queryData['conditions']['permissions']);
	        unset($queryData['permissions']);
	        return $queryData;
	    } elseif(!$this->isEnabled()) {
	        return true;
	    } elseif(!defined('PERMISSION_GROUP_BITS') or !defined('PERMISSION_USER_ID')) {
	        $queryData['conditions'] = '1=0';
	    } elseif((PERMISSION_GROUP_BITS & 1) <> 0) {
	        return true;
	    } else {
	        $alias = $model->Permission->alias;

	        $queryData['joins'][]  = array(
                'table'     => $model->Permission->table,
                'alias'     => $alias,
                'type'      => 'INNER',
                'foreignKey'=> false,
                'conditions'=> array(
                    "$alias.model = '{$model->alias}'",
                    "$alias.foreign_key = {$model->alias}.{$model->primaryKey}",
                    'or' => $this->getPermissionQuery($model)
                )
            );
	    }

	    return $queryData;
	}

	public function beforeSave(&$model) {
	    if(!$this->isEnabled()) {
	        return true;
	    }

	    $id = null;

	    if(!empty($model->id)) {
	        $id = $model->id;
	    } elseif(
	       !empty($model->data) and
	       isset($model->data[$model->alias]) and
           isset($model->data[$model->alias]['id']) and
           !empty($model->data[$model->alias]['id'])) {
	        $id = $model->data[$model->alias]['id'];
	    }

            if($model->alias == $this->settings[$model->alias]['groupModel'] and empty($id)) {
                $next_bit   = 1;
                $max_bit    = $model->field('bit', null, "{$model->alias}.bit DESC");

                if(!empty($max_bit)) {
                    $next_bit = $max_bit * 2;
                }

                $this->set('bit', $next_bit);
            }

            return (!empty($id))
	           ? $this->hasPermission($model, 'write', $id)
	           : true;
	}

	private function backout(&$model) {
	    $model->del();
	    return false;
	}

	private function getModel(&$model, $name = null) {

	    if(empty($name)) {
	        return null;
	    }

	    if(isset($model->{$name})) {
	        $theModel =& $model->{$name};
	    } else {
	        $theModel =& ClassRegistry::init($name);
	    }

	    return $theModel;
	}

	private function getPermissionBits(&$model) {
	    return (isset($model->data['permission']) and
	            !empty($model->data['permission']))
                    ? $model->data['permission']
                    : (isset($model->data[$model->alias]) and
                       isset($model->data[$model->alias]['permission']) and
                       !empty($model->data[$model->alias]['permission']))
                        ? $model->data[$model->alias]['permission']
                        : $this->settings[$model->alias]['defaultBits'];
	}

	private function getPermissionQuery(&$model, $action = 'read') {
	    $alias = $model->Permission->alias;
	    $perms = $this->__permissions;

	    return array(
            "$alias.permission & {$perms['other_'.$action]} <> 0",
            array(
                "$alias.permission & {$perms['group_'.$action]} <> 0",
                "$alias.group_bits & ". PERMISSION_GROUP_BITS ." <> 0"
            ),
            array(
                "$alias.permission & {$perms['owner_'.$action]} <> 0",
                "$alias.user_id = '". PERMISSION_USER_ID ."'"
            )
        );
	}

	public function hasPermission(&$model, $action = 'read', $id = null) {
	    if(!$this->isEnabled()) {
	        return true;
	    }

	    if((PERMISSION_GROUP_BITS & 1) <> 0) {
	        return true;
	    } elseif(empty($id) and empty($model->id)) {
	        return false;
	    }

	    $permission = $model->Permission->find('count', array(
            'recursive'     => -1,
            'conditions'    => array(
                'model'         => $model->alias,
                'foreign_key'   => (!empty($id)
                                ?  $id
                                :  $model->id),
                'or'            => $this->getPermissionQuery($model, $action)
            )
	    ));

	    return (!empty($permission) and $permission > 0);
	}

	private function isEnabled() {
	    return $this->__enabled;
	}

	private function isTree(&$model) {
	    return $model->Behaviors->attached('Tree');
	}

	public function setUserData(&$model, $data = array()) {
	    if(empty($data)) {
	        return;
	    }

	    $modelNames = am(array_values($model->tableToModel), array($model->alias));

	    foreach($modelNames as $modelName) {
	        if(!isset($this->settings[$modelName])) {
	            $this->settings[$modelName] = $this->__defaults;
	        }

	        $this->settings[$modelName]['userData'] = $data;
	    }
	}

}

How To Use

first off, there are a couple of caveats, as with anything that’s not 100% ready for release and built primarily for my use.

• my app uses UUIDs, so you might need to adjust sql/code if you don’t
• groups are hierarchical, and thus tree-behaviored
• there must be a “root” group with a bit of 1, and a “root” user in that group.  any other groups must be created as siblings to the root group (not children!)
• if you use the Auth component to control your app, you’ll need to set the scope for Auth, ala: $this->Auth->userScope = array(‘permissions’ => false);
• if you use this on a tree-behaviored model besides the group model, you will need to handle inherited permissions (if you want that)
• there are other missing knicknacks, specifically updating the user’s group_bits when you add/remove groups, or if you add/remove the user from groups.  actually, now that i think about it, removing a group won’t cause a problem, so long as you skip the removed group’s bit when adding a new group.  i’ll explain why in a bit.  and there isn’t a way to override the owner or group_bit for a record as of the moment.  i’ll add that soon.

you will need to create the appropriate tables:

CREATE TABLE `groups` (
  `id` char(36) collate utf8_unicode_ci NOT NULL,
  `parent_id` char(36) collate utf8_unicode_ci default NULL,
  `lft` int(3) NOT NULL,
  `rght` int(3) NOT NULL,
  `name` varchar(100) collate utf8_unicode_ci NOT NULL,
  `bit` int(11) NOT NULL,
  PRIMARY KEY  (`id`),
  KEY `parent_id` (`parent_id`),
  KEY `lft` (`lft`,`rght`),
  KEY `bit` (`bit`)
) DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

CREATE TABLE `groups_users` (
  `id` int(11) NOT NULL auto_increment,
  `group_id` char(36) collate utf8_unicode_ci NOT NULL,
  `user_id` char(36) collate utf8_unicode_ci NOT NULL,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `group_id` (`group_id`,`user_id`)
)  DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

CREATE TABLE `permissions` (
  `id` char(36) collate utf8_unicode_ci NOT NULL,
  `model` varchar(25) collate utf8_unicode_ci NOT NULL,
  `foreign_key` char(36) collate utf8_unicode_ci NOT NULL,
  `user_id` char(36) collate utf8_unicode_ci NOT NULL,
  `group_bits` int(11) NOT NULL default '0',
  `permission` int(3) unsigned zerofill NOT NULL default '000',
  PRIMARY KEY  (`id`),
  KEY `user_id` (`user_id`),
  KEY `group_bit` (`group_bits`),
  KEY `model` (`model`,`foreign_key`)
) DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

CREATE TABLE `users` (
  `id` char(36) collate utf8_unicode_ci NOT NULL,
  `password` char(40) collate utf8_unicode_ci NOT NULL,
  `email` varchar(255) collate utf8_unicode_ci NOT NULL,
  PRIMARY KEY  (`id`)
) DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

and that’s it! well, not really. you will need to add the behavior to each model you want to be permissioned:

public $actsAs = array('Permissionable');

you will need to put this code in AppController::beforeFilter(). this will inform the behavior who the user in question is, as well as what the group_bit is for the user (we’ll explain how this works later).

if you put this in some other controller’s beforeFilter you run the risk of permissioned associated models not knowing who the logged-in user is, i don’t recommend it. i’ll be moving this to a component in all likelihood, so it doesn’t have to live directly in any controller(s).

        $modelName  = Inflector::classify($this->name);
        $user_id    = $this->Auth->user('id');

        if(
            empty($user_id) or !isset($this->{$modelName}) or
            $this->{$modelName}->Behaviors->attached('Permissionable') == false
        ) {
            return;
        }

        $mainModel  = $this->{$modelName};
        $group_bits = $this->Session->read('Permission.group_bits');

        if(empty($group_bits)) {
            $permissionModel    =& $mainModel->Permission;
            $permissionBehavior = $mainModel->Behaviors->Permissionable;
            $group_bits         = $permissionModel->field('group_bits', array(
                'model'         => $permissionBehavior->settings[$mainModel->alias]['userModel'],
                'foreign_key'   => $user_id
            ));

            if(empty($group_bits)) {
                return;
            }

            $this->Session->write('Permission.group_bits', $group_bits);
        }

        define('PERMISSION_USER_ID',    $user_id);
        define('PERMISSION_GROUP_BITS', $group_bits);

after that, any new record that is created will have a permission set, the creating user being the owner, and the groups that the user is in as the group_bit for the permission.  this means that every group the user is in will have the same group level permissions that the creating user has.  for example:  if the record is created with the permissions of (user read/write/delete, group read/write, others read), then any member of any group that the creator is in will also have read/write permissions on that record, while the author will additionally have delete permission, and all others will have read.

now, if you want to override the default permissions, you can do so in the model by setting the $defaultBits property to the desired permission for that model.  additionally, you can set $model->data['permission'] or $model->data[$modelName]['permission'] to the desired permission for the row being saved.

So, how does it work, Mr. Wizard?

well, the simple answer is “bitwise”-ly.  without going into tedious detail, we make use of bitwise operators in php (and sql) to determine what type of operation we are trying to accomplish (selects are reads, updates are writes and deletes are deletes), we check whether or not the user is either the owner of the row, in a group that the record in question is also in, or if “other” permissions allow them to do what they are asking.  some quick examples:

• group A has bit of 1 (root)
• group B has bit of 2
• group C has bit of 4
• group D has a bit of 8
• user 1 has a group_bit of 1 (root)
• user 2 has a group_bit of 6 (group B + group C)
• user 3 has a group_bit of 8 (group D)
• record is owned by user 2, has a group_bit of 6 (group B + group C) and a permission of 416 (owner read (256) + owner write (128) + group read (32) = 416)

user 1 (root) tries to select the record.  since he’s root (bit 1), he’s allowed.

user 2 tries to select record. he’s not the record owner, so permissions are checked to see if it contains the “group read” bit: (416 & 32 <> 0) == true, and then the record’s group_bit is checked to see if the user has a matching group bit: (6 & 6 <> 0) == true.  both checks are true, so the user can read the row.

user 3 tries to select record. he’s not the record owner, so group permissions are checked: (416 & 32 <> 0) == true, and then group_bit is checked: (6 & 8 <> 0) == false, then other_read permissions are checked (416 & 4 <> 0) == false, so the user is denied access to the row.

probably the nicest thing about this method is that instead of having to do separate queries in a beforeFind to determine if the query should continue or how to filter the original query, all the behavior does is add a join to the query on the permissions table.  all of your single queries to find matching records stay single queries.  there still are pre-checks when trying to update or delete a record, but they are quick and relatively painless.  there’s nothing else to really change.  all your find calls will work like before, except they will only return allowed rows.  save()/delete() calls will return false if the row doesn’t have write access for the user trying to do so.  inserting isn’t covered by this method though, that’s where ACLs come into play… and that’s what the follow-up article will cover.

so there you have it.  since this is only mostly finished, i welcome fixes, comment, critique and/or praise.

i think that Prototype (Prototype is dead! Long live Prototype!) and jQuery have something to worry about.

check it out.

funny:  “Unix is user friendly. It’s just very particular about who it’s friends are.”

informative: “In computer science, tree-traversal refers to the process of visiting (examining and/or updating) each node in a tree data structure, exactly once, in a systematic way. Such traversals are classified by the order in which the nodes are visited.” — wikipedia

trite: see post title.

check.