Every Wave that is sent from one Particle to another references an Agent which is just a Point that access rules can be applied to. Usually a Particle sends itself as the Agent, but there are cases where It can use other Agents if the Hyperverse allows it.


The HyperUser is the only user that access is not checked on. It can do anything (just like the Root user in unix OS.)


to grant permission on a particle to a particle:

grant perm +csd-Rwx on** to**<User>

Above we are granting READ access to all users under on every particle under

Let's examine this part: +csd-Rwx The letters stand for Create, Select, Delete, Read, Write and Execute. if the letter is capitalized then the permission is flagged as on, if lowercase it is off.

Also note the leading + operator. That is saying to OR these permissions with existing permissions. You can also choose to AND the permissions via the & operator which would have looked like this:

grant perm &csd-Rwx on** to**<User>

NOTE: The rules of how the Ands and the Ors are combined are consistent but a bit tricky and I will expand on it in a later iteration of this document -- uberscott


First let's break down CSD:

  • CREATE - Permission to create children under the Particle
  • SELECT - Permission to select this Particle and children
  • DELETE - Permission to delete this Particle and children


Let's break down the RWX:

  • READ - Permission to read the state of the Particle (not all particles have state)
  • WRITE - Permission to write the state of the Particle (not all particles have state)
  • EXECUTE - Permission to send Waves to the Particle


Sometimes security has to be a little more fine-grained that broad permissions. For this we have Privileges.

One built in Privilege in the system is the User email property. Even if a Particle has full CSD-RWX access to a User Particle it cannot get the value of the email property unless it has been granted privilege to do so.

To grant a privilege:

grant priv prop:email<Read> on**<User> to

As you can see above we are giving only one mechtron in our application, the emailer mecthtron the privilege to see the email addresses, all other mechtrons are untrusted.


You can list the grants on a particular Pattern:

grant list on**;

And that will result in a list with a numbered id with every grant. You can then revoke the grant using the number:

grant revoke 1


When a Particle creates another Particle that Particle owns it and perform any action upon it full permissions and full privileges. To change ownership:

chown localhost:users:uberscott localhost:something;


There are times when you may want to capture and reuse a segment to make more complicated permission rules

grant perm +CSR-RWX on$(user) to${user}

Above the variable user is captured in profiles and filled in the UserBase giving each user complete access to his or her own profile.


The HyperUser has complete access to the entire Cosmos, however it is also desirable to have SuperUsers which have complete access to only a portion of the overall cosmos. To accomplish this we can grant another user SuperUser access:

grant super on** to<User>

Above you can see that what-a-great-guy has been granted superuser access to everything under the my-domain, and he will have full access to anything that matches that pattern,

The use of SuperUser can be particularly useful for Apps which may need to control every aspect of their children:

grant super on** to<App>

above the App can now administer itself and its children with full access.